339 lines
6.8 KiB
Markdown
339 lines
6.8 KiB
Markdown
# Troubleshooting
|
|
|
|
Operational diagnosis guide for common Narratio failures.
|
|
|
|
## Config file not found
|
|
|
|
Symptom:
|
|
|
|
- command fails to resolve `pipeline.yml`, `campaign.yml`, or `session.yml`.
|
|
|
|
Likely causes:
|
|
|
|
- missing files in default search paths;
|
|
- wrong campaign selection;
|
|
- omitted explicit flags.
|
|
|
|
Diagnostics:
|
|
|
|
```bash
|
|
narratio session plan 2026-04-04
|
|
```
|
|
|
|
Safe fix:
|
|
|
|
- pass explicit `--config`, `--campaign` or `--campaign-file`, and `--session`.
|
|
|
|
Relevant reference: [Configuration discovery](./config.md#discovery-and-selection).
|
|
|
|
## Session template placeholders rejected
|
|
|
|
Symptom:
|
|
|
|
- load error says session file must be concrete or contains `{{ ... }}` placeholders.
|
|
|
|
Likely cause:
|
|
|
|
- using template content as runtime session config.
|
|
|
|
Diagnostics:
|
|
|
|
```bash
|
|
narratio session validate 2026-04-04 --session /path/session.yml
|
|
```
|
|
|
|
Safe fix:
|
|
|
|
- generate concrete session YAML with `narratio session init`.
|
|
|
|
Relevant reference: [Operations: Session Initialization](./operations.md#session-initialization).
|
|
|
|
## Strict decode or schema validation failure
|
|
|
|
Symptom:
|
|
|
|
- unknown field / invalid value error during config load.
|
|
|
|
Likely cause:
|
|
|
|
- stale field name, typo, invalid enum, or invalid duration/path format.
|
|
|
|
Diagnostics:
|
|
|
|
```bash
|
|
narratio session plan 2026-04-04 --config /path/pipeline.yml --campaign-file /path/campaign.yml --session /path/session.yml
|
|
```
|
|
|
|
Safe fix:
|
|
|
|
- align config with [Configuration](./config.md) and the
|
|
[maintained examples](../examples/README.md).
|
|
|
|
Relevant reference: [Configuration](./config.md).
|
|
|
|
## Audio mode conflict
|
|
|
|
Symptom:
|
|
|
|
- validation fails on session audio configuration.
|
|
|
|
Likely cause:
|
|
|
|
- configured both local and S3 session audio inputs.
|
|
|
|
Diagnostics:
|
|
|
|
```bash
|
|
narratio session validate 2026-04-04
|
|
```
|
|
|
|
Safe fix:
|
|
|
|
- use local mode (`audio_dir` or `audio_files`) or S3 mode (`audio_s3.prefix`), not both.
|
|
|
|
Relevant reference: [Session configuration](./config.md#session).
|
|
|
|
## `--artifacts` selection error
|
|
|
|
Symptom:
|
|
|
|
- unknown artifact key or invalid `--artifacts` usage.
|
|
|
|
Likely causes:
|
|
|
|
- key not defined in `pipeline.scriptorium.artifacts`;
|
|
- empty list entry (for example trailing comma);
|
|
- `run-stage` used with non-`analyze`/`publish` target.
|
|
|
|
Diagnostics:
|
|
|
|
```bash
|
|
narratio session artifacts 2026-04-04
|
|
```
|
|
|
|
Safe fix:
|
|
|
|
- provide only configured keys and use `--artifacts` with supported commands/stages.
|
|
|
|
Relevant reference: [CLI artifact selection](./cli.md).
|
|
|
|
## Previous-session artifact input missing
|
|
|
|
Symptom:
|
|
|
|
- prepare/analyze fails due to missing required previous-session artifact cache input.
|
|
|
|
Likely causes:
|
|
|
|
- missing `session.previous_session_id`;
|
|
- previous artifact not restored/published for source session.
|
|
|
|
Diagnostics:
|
|
|
|
```bash
|
|
narratio session validate 2026-04-04
|
|
narratio session status 2026-04-04
|
|
```
|
|
|
|
Safe fix:
|
|
|
|
```bash
|
|
narratio session restore 2026-04-04
|
|
```
|
|
|
|
or rerun prepare after correcting session config:
|
|
|
|
```bash
|
|
narratio run-stage prepare 2026-04-04 --force
|
|
```
|
|
|
|
Relevant reference: [Operations: Restore Workflow](./operations.md#restore-workflow).
|
|
|
|
## Session lock conflict (`.lock`)
|
|
|
|
Symptom:
|
|
|
|
- command fails acquiring session lock.
|
|
|
|
Likely causes:
|
|
|
|
- another process is running for the same session;
|
|
- stale lock left by interrupted process.
|
|
|
|
Diagnostics:
|
|
|
|
```bash
|
|
ls -l {workspace.root}/work/{campaign}/{session_id}/.lock
|
|
ps aux | grep narratio
|
|
```
|
|
|
|
Safe fix:
|
|
|
|
- wait for active process completion;
|
|
- remove stale lock only after confirming no live process owns it.
|
|
|
|
Relevant reference: [Operations: Local State Layout](./operations.md#local-state-layout).
|
|
|
|
## Restore conflict without `--force`
|
|
|
|
Symptom:
|
|
|
|
- restore fails with conflict count.
|
|
|
|
Likely cause:
|
|
|
|
- local durable files differ from remote restore sources.
|
|
|
|
Diagnostics:
|
|
|
|
```bash
|
|
narratio session restore 2026-04-04 --dry-run
|
|
```
|
|
|
|
Safe fix:
|
|
|
|
- review conflicts;
|
|
- rerun with `--force` only when remote state should overwrite local.
|
|
|
|
Relevant reference: [Operations: Restore Workflow](./operations.md#restore-workflow).
|
|
|
|
## Restore current-state discovery failure
|
|
|
|
Symptom:
|
|
|
|
- restore cannot find current pointer or current manifest.
|
|
|
|
Likely causes:
|
|
|
|
- no committed publish current state;
|
|
- storage credentials or connectivity failure.
|
|
|
|
Diagnostics:
|
|
|
|
```bash
|
|
narratio session status 2026-04-04
|
|
narratio session restore 2026-04-04 --dry-run
|
|
```
|
|
|
|
Safe fix:
|
|
|
|
- resolve storage/auth issue;
|
|
- republish from healthy local state if current pointer is missing.
|
|
|
|
Relevant reference: [Operations: Publish Workflow](./operations.md#publish-workflow).
|
|
|
|
## Publish output failure
|
|
|
|
Symptom:
|
|
|
|
- publish fails on missing required source, upload error, or commit write.
|
|
|
|
Likely causes:
|
|
|
|
- required source file not produced;
|
|
- lock/state expectations mismatch;
|
|
- remote storage failure.
|
|
|
|
Diagnostics:
|
|
|
|
```bash
|
|
narratio session artifacts 2026-04-04 --remote
|
|
narratio session status 2026-04-04
|
|
narratio run-stage publish 2026-04-04 --force
|
|
```
|
|
|
|
Safe fix:
|
|
|
|
- regenerate missing sources by rerunning prerequisite stages;
|
|
- correct publish source/destination rules;
|
|
- retry after storage failure is resolved.
|
|
|
|
Relevant reference: [Publish configuration](./config.md#publish-configuration-summary).
|
|
|
|
## Render markdown source missing
|
|
|
|
Symptom:
|
|
|
|
- analyze or publish fails because `narratio.transcript.final_markdown` or `narratio.transcript.final_trimmed_markdown` is unavailable.
|
|
|
|
Likely causes:
|
|
|
|
- render stage was not executed after transcript changes;
|
|
- render stage failed before producing canonical markdown outputs.
|
|
|
|
Diagnostics:
|
|
|
|
```bash
|
|
narratio session status 2026-04-04
|
|
```
|
|
|
|
Safe fix:
|
|
|
|
- rerun render and then retry downstream stage(s):
|
|
|
|
```bash
|
|
narratio run-stage render 2026-04-04 --force
|
|
narratio run-stage analyze 2026-04-04 --force
|
|
```
|
|
|
|
Relevant reference: [Operations: Stage Execution](./operations.md#stage-execution-and-continuation-behavior).
|
|
|
|
## Secrets or storage credential failure
|
|
|
|
Symptom:
|
|
|
|
- object-store command fails at initialization/auth.
|
|
|
|
Likely causes:
|
|
|
|
- invalid `pipeline.secrets.env_dir`;
|
|
- missing credential environment variables;
|
|
- invalid S3 endpoint/bucket settings.
|
|
|
|
Diagnostics:
|
|
|
|
```bash
|
|
ls -la /path/to/secrets_dir
|
|
env | grep -E 'OBJECT_STORAGE|AWS|AUDITA|SCRIPTORIUM'
|
|
```
|
|
|
|
Safe fix:
|
|
|
|
- correct secret-file path and permissions;
|
|
- provide required env vars;
|
|
- keep secret values out of YAML.
|
|
|
|
Relevant reference: [Secrets](./config.md#secrets-handling).
|
|
|
|
## S3 audio prepare failure
|
|
|
|
Symptom:
|
|
|
|
- prepare fails listing/downloading session S3 audio.
|
|
|
|
Likely causes:
|
|
|
|
- incorrect `session.inputs.audio_s3.prefix`;
|
|
- no matching `.flac` objects;
|
|
- storage connectivity or permissions failure.
|
|
|
|
Diagnostics:
|
|
|
|
```bash
|
|
narratio session validate 2026-04-04
|
|
```
|
|
|
|
Safe fix:
|
|
|
|
- verify prefix contents and storage access;
|
|
- keep session audio mode consistent.
|
|
|
|
Relevant reference: [Operations](./operations.md).
|
|
|
|
## References
|
|
|
|
- [docs/cli.md](./cli.md)
|
|
- [docs/config.md](./config.md)
|
|
- [docs/operations.md](./operations.md)
|
|
- [docs/internal/stage-publish.md](./internal/stage-publish.md)
|