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

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

## 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 [docs/config.md](./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:

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

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

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

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

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

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

## 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 run-stage prepare 2026-04-04 --force
```

Safe fix:

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

## 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)