narratio/docs/troubleshooting.md

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:

narratio session plan 2026-04-04

Safe fix:

• pass explicit --config, --campaign or --campaign-file, and --session.

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:

narratio session validate 2026-04-04 --session /path/session.yml

Safe fix:

• generate concrete session YAML with narratio session init.

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:

narratio session plan 2026-04-04 --config /path/pipeline.yml --campaign-file /path/campaign.yml --session /path/session.yml

Safe fix:

• align config with docs/config.md and maintained files under examples/.

Audio mode conflict

Symptom:

• validation fails on session audio configuration.

Likely cause:

• configured both local and S3 session audio inputs.

Safe fix:

• use local mode (audio_dir or audio_files) or S3 mode (audio_s3.prefix), not both.

--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.

Safe fix:

• provide only configured keys and use --artifacts with supported commands/stages.

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:

narratio session validate 2026-04-04
narratio session status 2026-04-04

Safe fix:

narratio session restore 2026-04-04

or rerun prepare after correcting session config:

narratio run-stage prepare 2026-04-04 --force

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:

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.

Restore conflict without --force

Symptom:

• restore fails with conflict count.

Likely cause:

• local durable files differ from remote restore sources.

Diagnostics:

narratio session restore 2026-04-04 --dry-run

Safe fix:

• review conflicts;
• rerun with --force only when remote state should overwrite local.

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:

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.

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:

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.

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:

narratio session status 2026-04-04
narratio run-stage render 2026-04-04 --force

Safe fix:

• rerun render and then retry downstream stage(s):

narratio run-stage render 2026-04-04 --force
narratio run-stage analyze 2026-04-04 --force

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:

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.

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:

narratio run-stage prepare 2026-04-04 --force

Safe fix:

• verify prefix contents and storage access;
• keep session audio mode consistent.

References

• docs/cli.md
• docs/config.md
• docs/operations.md
• docs/internal/stage-publish.md