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.

Relevant reference: Configuration discovery.

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.

Relevant reference: Operations: 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:

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 and the maintained examples.

Relevant reference: Configuration.

Audio mode conflict

Symptom:

• validation fails on session audio configuration.

Likely cause:

• configured both local and S3 session audio inputs.

Diagnostics:

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.

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

narratio session artifacts 2026-04-04

Safe fix:

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

Relevant reference: CLI artifact selection.

Notarius executable missing

Symptom:

• extraction fails while resolving or starting the Notarius executable.

Likely causes:

• pipeline.notarius.binary is not installed, executable, or on PATH;
• a configured executable path is wrong.

Safe fix:

• install a compatible Notarius release or correct the binary setting, then rerun extraction.

Relevant references: Notarius configuration and Notarius integration.

Notarius exits nonzero

Symptom:

• extraction reports a Notarius exit error instead of a receipt.

Diagnostics:

• inspect runs/{run_id}/extract/notarius.stderr.log; stdout is reserved for the receipt and is not merged with diagnostics.

Safe fix:

• correct the reported Notarius pipeline, input, provider, or configuration failure and rerun extraction. Do not edit a staged output bundle into place.

After a failed replacement, an older immutable bundle may still exist even though the current session manifest has no successful extraction payload. This is expected audit state, not a signal to relink the old bundle manually.

Relevant reference: Operations: Extraction Workflow.

Atomic Notarius promotion unsupported

Symptom:

• extraction fails with atomic no-replace directory promotion is unsupported before a durable bundle or temporary promotion tree is created.

Likely cause:

• Narratio is running on an operating system other than Linux, macOS, or Windows, where the required atomic no-replace directory primitive has not been implemented and verified.

Safe fix:

• run extraction on Linux, macOS, or Windows. Do not replace the atomic commit with a manual copy or move; the session manifest must never observe a partial or overwritten bundle.

This is an extraction-specific platform boundary, not a support statement for unrelated Narratio workflows. See Operations: Extraction Workflow.

Notarius receipt or index incompatible

Symptom:

• extraction rejects the receipt schema, pipeline identity, bundle/index path, lane descriptor, or payload path even though Notarius exited successfully.

Likely causes:

• Narratio and Notarius versions disagree on their consumer contract;
• the configured pipeline or lane constraints are stale;
• output paths escape the bundle or traverse symlinks.

Safe fix:

• compare installed Notarius output with the canonical Notarius contracts, including receipt index_file: index.json and index management names manifest.json, rejected.json, and warnings.json; align pipeline.notarius constraints and rerun. Do not bypass confinement or schema checks.

Relevant reference: Notarius integration.

Required Notarius lane rejected or missing

Symptom:

• extraction fails because a configured lane is rejected, missing, duplicated, or incompatible, including after a zero exit.

Safe fix:

• inspect the Notarius diagnostic log and bundle rejection/warning information;
• correct the Notarius module or the exact declared lane contract;
• remove an output declaration only if downstream consumers genuinely no longer require that source, then rerun extraction.

Every configured output is required. Narratio does not promote a partial result.

Extraction resume invalidated

Symptom:

• a previously successful extraction runs again during ordinary continuation.

Likely causes:

• the executable/config path, pipeline ID, timeout, working directory, or configured output contracts changed;
• the durable bundle, index, lane set, provenance, regular-file status, or checksum no longer validates.

Safe fix:

• allow the automatic rerun after verifying the current configuration. Treat an unsafe path or symlink error as filesystem corruption or tampering and investigate it rather than replacing files manually.

Notarius transitive configuration changed

Symptom:

• Notarius profiles, prompts, modules, imported files, or references changed, but Narratio still considers the previous extraction resumable.

Safe fix:

narratio run-stage extract 2026-04-04 --force

Narratio fingerprints its invocation contract, not the contents of transitive Notarius inputs. Always force extraction after changing them; downstream successful stages are then marked stale normally.

Relevant reference: Operations: Extraction Workflow.

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

Relevant reference: Operations: 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:

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.

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.

Relevant reference: Operations: 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:

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.

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.

Relevant reference: Publish configuration.

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

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

Relevant reference: Operations: Stage Execution.

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.

Relevant reference: Secrets.

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 session validate 2026-04-04

Safe fix:

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

Relevant reference: Operations.

References

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