Update documentation for the new analyze stage and artifact registry
This commit is contained in:
@@ -6,11 +6,11 @@ Canonical operator troubleshooting guide for recurring implemented Narratio fail
|
||||
## Config file discovery failure
|
||||
|
||||
Symptom:
|
||||
- `run`, `plan`, `resume`, or `run-stage` fails saying config/session file was not found.
|
||||
- `run`, `plan`, `resume`, or `run-stage` fails with config/session not found.
|
||||
|
||||
Likely Cause:
|
||||
- `pipeline.yml` or `session.yml` is missing from default search paths.
|
||||
- Wrong working directory when relying on `./session.yml`.
|
||||
- `pipeline.yml` or `session.yml` is missing from discovery paths.
|
||||
- wrong working directory when relying on `./session.yml`.
|
||||
|
||||
Diagnostics:
|
||||
|
||||
@@ -21,8 +21,8 @@ ls -l /usr/local/etc/narratio/pipeline.yml /etc/narratio/pipeline.yml
|
||||
```
|
||||
|
||||
Safe Fix:
|
||||
- Pass explicit paths with `--config` and `--session`.
|
||||
- Or place files in documented discovery paths.
|
||||
- pass explicit `--config` and `--session`.
|
||||
- or place files in documented discovery paths.
|
||||
|
||||
Links:
|
||||
- [docs/config.md](./config.md)
|
||||
@@ -31,11 +31,11 @@ Links:
|
||||
## Session template rendering failure
|
||||
|
||||
Symptom:
|
||||
- Load fails with unresolved template placeholder or `session_id` mismatch.
|
||||
- load fails with unresolved placeholder or `session_id` mismatch.
|
||||
|
||||
Likely Cause:
|
||||
- `session.yml` contains `{{session_id}}`/`{{ session_id }}` but `--session-id` was omitted.
|
||||
- Provided `--session-id` does not match rendered `session_id`.
|
||||
- templated `session.yml` used without `--session-id`.
|
||||
- rendered `session_id` differs from passed `--session-id`.
|
||||
|
||||
Diagnostics:
|
||||
|
||||
@@ -44,8 +44,8 @@ narratio plan --session ./session.yml --session-id 2026-04-04
|
||||
```
|
||||
|
||||
Safe Fix:
|
||||
- Always pass `--session-id` when using template placeholders.
|
||||
- Ensure rendered `session_id` equals intended run session id.
|
||||
- pass `--session-id` when template placeholders are present.
|
||||
- ensure rendered `session_id` matches intended run session id.
|
||||
|
||||
Links:
|
||||
- [docs/config.md](./config.md)
|
||||
@@ -53,12 +53,11 @@ Links:
|
||||
## Strict YAML decode or validation failure
|
||||
|
||||
Symptom:
|
||||
- Config load fails with unknown field, missing required field, invalid duration, or invalid cross-field constraint.
|
||||
- config load fails with unknown field or validation error.
|
||||
|
||||
Likely Cause:
|
||||
- YAML key typo or stale field name.
|
||||
- Required fields missing.
|
||||
- Invalid value format (for example duration/URL/env var name).
|
||||
- typo/stale field name.
|
||||
- missing required fields or invalid constraints.
|
||||
|
||||
Diagnostics:
|
||||
|
||||
@@ -67,22 +66,114 @@ narratio plan --config /path/to/pipeline.yml --session /path/to/session.yml --se
|
||||
```
|
||||
|
||||
Safe Fix:
|
||||
- Correct fields/values to match canonical reference and examples.
|
||||
- Validate against `docs/examples/` shapes.
|
||||
- align fields/values to canonical config reference and examples.
|
||||
|
||||
Links:
|
||||
- [docs/config.md](./config.md)
|
||||
- [docs/examples/](./examples/)
|
||||
|
||||
## `--artifacts` selection failure
|
||||
|
||||
Symptom:
|
||||
- `run`/`resume`/`run-stage` fails with invalid or unknown artifact selection.
|
||||
|
||||
Likely Cause:
|
||||
- `--artifacts` contains blank names or unknown artifact keys.
|
||||
- `pipeline.scriptorium.artifacts` missing while using `--artifacts`.
|
||||
|
||||
Diagnostics:
|
||||
|
||||
```bash
|
||||
narratio run --config /path/to/pipeline.yml --session /path/to/session.yml --session-id 2026-04-04 --artifacts player_handout
|
||||
```
|
||||
|
||||
Safe Fix:
|
||||
- use configured artifact keys only.
|
||||
- ensure `pipeline.scriptorium.artifacts` is defined.
|
||||
|
||||
Links:
|
||||
- [docs/cli.md](./cli.md)
|
||||
- [docs/config.md](./config.md)
|
||||
|
||||
## `run-stage --artifacts` on non-analyze stage
|
||||
|
||||
Symptom:
|
||||
- `run-stage` fails with `--artifacts is only supported for stage "analyze"`.
|
||||
|
||||
Likely Cause:
|
||||
- `--artifacts` was used with a non-`analyze` stage.
|
||||
|
||||
Diagnostics:
|
||||
|
||||
```bash
|
||||
narratio run-stage --config /path/to/pipeline.yml --session /path/to/session.yml --session-id 2026-04-04 --artifacts session_recap polish
|
||||
```
|
||||
|
||||
Safe Fix:
|
||||
- use `--artifacts` only with `run-stage ... analyze`.
|
||||
|
||||
Links:
|
||||
- [docs/cli.md](./cli.md)
|
||||
|
||||
## Configured artifact dependency/input validation failure
|
||||
|
||||
Symptom:
|
||||
- config validation fails for `depends_on`, `narratio.artifact.<name>` source, or artifact output path.
|
||||
|
||||
Likely Cause:
|
||||
- `narratio.artifact.<name>` source missing matching `depends_on` key.
|
||||
- dependency references unknown artifact key.
|
||||
- dependency self-reference or enabled dependency cycle.
|
||||
- artifact output path missing/invalid/outside `artifacts/` root.
|
||||
|
||||
Diagnostics:
|
||||
|
||||
```bash
|
||||
narratio plan --config /path/to/pipeline.yml --session /path/to/session.yml --session-id 2026-04-04
|
||||
```
|
||||
|
||||
Safe Fix:
|
||||
- ensure artifact-to-artifact inputs have explicit `depends_on` entries using artifact keys.
|
||||
- ensure referenced artifacts exist and define valid `output_path` values.
|
||||
- keep output paths relative and under `artifacts/`.
|
||||
|
||||
Links:
|
||||
- [docs/config.md](./config.md)
|
||||
- [docs/internal/stage-analyze.md](./internal/stage-analyze.md)
|
||||
|
||||
## Required configured artifact input unavailable at analyze time
|
||||
|
||||
Symptom:
|
||||
- analyze fails because configured input source is unavailable.
|
||||
|
||||
Likely Cause:
|
||||
- required upstream configured artifact was not selected/executed this run.
|
||||
- non-executable dependency output file is missing or invalid on disk.
|
||||
|
||||
Diagnostics:
|
||||
|
||||
```bash
|
||||
narratio status --manifest /path/to/manifest.json
|
||||
narratio run-stage --config /path/to/pipeline.yml --session /path/to/session.yml --session-id 2026-04-04 --artifacts player_handout analyze
|
||||
```
|
||||
|
||||
Safe Fix:
|
||||
- run analyze with needed artifacts selected.
|
||||
- or ensure dependency output file exists at configured path and is valid.
|
||||
|
||||
Links:
|
||||
- [docs/operations.md](./operations.md)
|
||||
- [docs/config.md](./config.md)
|
||||
|
||||
## Manifest/status path failure
|
||||
|
||||
Symptom:
|
||||
- `status` fails because manifest path is missing, unreadable, or invalid.
|
||||
|
||||
Likely Cause:
|
||||
- Wrong manifest path.
|
||||
- Manifest removed after cleanup.
|
||||
- Trying to run `status` without `--manifest`.
|
||||
- wrong manifest path.
|
||||
- manifest removed after cleanup.
|
||||
- `--manifest` omitted.
|
||||
|
||||
Diagnostics:
|
||||
|
||||
@@ -92,8 +183,7 @@ ls -l /path/to/manifest.json
|
||||
```
|
||||
|
||||
Safe Fix:
|
||||
- Use manifest path printed by `run`, `resume`, or `run-stage` output.
|
||||
- Re-run with correct session/config if inspecting a different session.
|
||||
- use manifest path printed by `run`, `resume`, or `run-stage`.
|
||||
|
||||
Links:
|
||||
- [docs/cli.md](./cli.md)
|
||||
@@ -102,11 +192,11 @@ Links:
|
||||
## Session lock conflict (`.lock`)
|
||||
|
||||
Symptom:
|
||||
- Run fails with lock conflict indicating session workdir is already locked.
|
||||
- run fails with lock conflict for session workdir.
|
||||
|
||||
Likely Cause:
|
||||
- Another Narratio process is actively running the same session.
|
||||
- Prior run exited unexpectedly and left a stale lock file.
|
||||
- another Narratio process is running same session.
|
||||
- stale lock from interrupted prior run.
|
||||
|
||||
Diagnostics:
|
||||
|
||||
@@ -117,21 +207,21 @@ ps aux | grep narratio
|
||||
```
|
||||
|
||||
Safe Fix:
|
||||
- If another run is active, wait for it to finish.
|
||||
- If no process is active and lock is stale, remove only that session `.lock` file and retry.
|
||||
- wait for active run to finish.
|
||||
- if no process is active, remove only stale session `.lock` file.
|
||||
|
||||
Links:
|
||||
- [docs/operations.md](./operations.md)
|
||||
- [docs/internal/workspace.md](./internal/workspace.md)
|
||||
|
||||
## Secrets env-dir or credential env failure
|
||||
## Secrets env-dir or credential-env failure
|
||||
|
||||
Symptom:
|
||||
- Startup fails loading secrets directory, or a stage fails because required credential env var is missing.
|
||||
- startup fails loading secrets directory, or stage fails due to missing credential env vars.
|
||||
|
||||
Likely Cause:
|
||||
- `pipeline.secrets.env_dir` path is wrong/unreadable.
|
||||
- Credential env var referenced in config is unset or empty.
|
||||
- invalid `pipeline.secrets.env_dir` path/permissions.
|
||||
- required credential env var unset/empty.
|
||||
|
||||
Diagnostics:
|
||||
|
||||
@@ -141,24 +231,22 @@ env | grep -E 'AUDITA|OBJECT_STORAGE|AWS|SCRIPTORIUM'
|
||||
```
|
||||
|
||||
Safe Fix:
|
||||
- Fix `pipeline.secrets.env_dir` path/permissions.
|
||||
- Ensure required env vars are set to non-empty values.
|
||||
- Keep secrets out of YAML; use env references only.
|
||||
- fix secrets directory and credential env vars.
|
||||
- keep secret values out of YAML.
|
||||
|
||||
Links:
|
||||
- [docs/config.md](./config.md)
|
||||
- [docs/operations.md](./operations.md)
|
||||
|
||||
## S3-audio prepare failure
|
||||
|
||||
Symptom:
|
||||
- `prepare` fails in S3 mode (no audio found, list/download failure, backend missing, path conflict).
|
||||
- `prepare` fails in S3 mode (listing/downloading/no audio/backend error).
|
||||
|
||||
Likely Cause:
|
||||
- Wrong `session.inputs.audio_s3.prefix`.
|
||||
- No `.flac` files at expected prefix.
|
||||
- Missing or invalid S3 backend credentials/config.
|
||||
- Conflicting audio-source settings (`audio_s3` plus local audio fields).
|
||||
- wrong `session.inputs.audio_s3.prefix`.
|
||||
- no `.flac` files at resolved prefix.
|
||||
- invalid/missing object-store credentials or backend config.
|
||||
- mixed local+S3 audio input config.
|
||||
|
||||
Diagnostics:
|
||||
|
||||
@@ -167,24 +255,21 @@ narratio run-stage --config /path/to/pipeline.yml --session /path/to/session.yml
|
||||
```
|
||||
|
||||
Safe Fix:
|
||||
- Ensure `audio_s3` is the only audio source configured for that session.
|
||||
- Confirm `.flac` objects exist under the resolved session audio prefix.
|
||||
- Fix S3 storage configuration and credentials.
|
||||
- configure exactly one audio source mode.
|
||||
- verify `.flac` files and storage access.
|
||||
|
||||
Links:
|
||||
- [docs/config.md](./config.md)
|
||||
- [docs/operations.md](./operations.md)
|
||||
- [docs/internal/stage-prepare.md](./internal/stage-prepare.md)
|
||||
|
||||
## Archive prerequisite or promotion/current-pointer failure
|
||||
## Archive promotion/current-pointer failure
|
||||
|
||||
Symptom:
|
||||
- `archive` fails due to prerequisite stage status, missing required promotion source, or pointer write failure.
|
||||
- archive fails on required promotion source missing or pointer write failure.
|
||||
|
||||
Likely Cause:
|
||||
- One or more prerequisite stages are not `succeeded`.
|
||||
- Required promoted artifact does not exist.
|
||||
- Remote upload failure before `current/run_id.txt` write.
|
||||
- required promoted file absent (including analyze outputs not generated for this run).
|
||||
- storage upload failed before `current/run_id.txt` commit marker write.
|
||||
|
||||
Diagnostics:
|
||||
|
||||
@@ -194,36 +279,11 @@ narratio run-stage --config /path/to/pipeline.yml --session /path/to/session.yml
|
||||
```
|
||||
|
||||
Safe Fix:
|
||||
- Resume or rerun failed upstream stage(s).
|
||||
- Ensure required promoted artifact paths exist locally before archive.
|
||||
- Retry archive after storage/connectivity issue is resolved.
|
||||
- rerun or resume upstream stages to generate required files.
|
||||
- adjust promotion rules to match files that must exist.
|
||||
- retry after storage issue is resolved.
|
||||
|
||||
Links:
|
||||
- [docs/operations.md](./operations.md)
|
||||
- [docs/config.md](./config.md)
|
||||
- [docs/internal/stage-archive.md](./internal/stage-archive.md)
|
||||
|
||||
## `run-stage` invalid stage name or invalid flags
|
||||
|
||||
Symptom:
|
||||
- `run-stage` fails with unknown stage or invalid flag/argument usage.
|
||||
|
||||
Likely Cause:
|
||||
- Stage name typo.
|
||||
- Missing positional stage argument.
|
||||
- Unsupported/incorrect flag syntax.
|
||||
|
||||
Diagnostics:
|
||||
|
||||
```bash
|
||||
narratio run-stage --config /path/to/pipeline.yml --session /path/to/session.yml --session-id 2026-04-04 normalize
|
||||
```
|
||||
|
||||
Safe Fix:
|
||||
- Use only supported stage names.
|
||||
- Provide exactly one positional stage argument.
|
||||
- Align flags to documented command reference.
|
||||
|
||||
Links:
|
||||
- [docs/cli.md](./cli.md)
|
||||
- [docs/operations.md](./operations.md)
|
||||
|
||||
Reference in New Issue
Block a user