# Troubleshooting This guide maps common implemented failure modes to inspection steps and fixes. For command syntax, see [CLI Reference](cli.md). For YAML fields and environment overrides, see [Configuration](config.md). For output and diagnostics layout, see [Operations](operations.md). ## Config File Not Found Symptom: ```text notarius: config file not found; pass --config or set NOTARIUS_CONFIG ``` Fix: - Pass `--config path/to/config.yml`. - Or set `NOTARIUS_CONFIG` to a readable file. - Or install a config at `/usr/local/etc/notarius/config.yml`. If the message says the config path is a directory or is not available, correct the path or file permissions. ## Unsupported Or Invalid Config Symptoms include: - `unsupported config version` - `config version is required` - `field not found` - `total LLM concurrency must be greater than zero` - `diagnostics retention "" is not supported` Fix: - Use `version: 2`. - Remove unknown YAML fields. - Validate with: ```sh go run ./cmd/notarius config validate --config path/to/config.yml ``` ## Unknown Pipeline Symptom: ```text notarius: pipeline "..." is not configured ``` Fix: - List configured pipeline IDs: ```sh go run ./cmd/notarius pipelines list --config path/to/config.yml ``` - Use one of those IDs in `notarius run `. - Check indentation under the top-level `pipelines` map. ## Unknown Or Incompatible Module Symptoms mention a module key, pipeline slot, lane, capability, or `not registered`. Fix: - Validate the pipeline against the production module catalog: ```sh go run ./cmd/notarius config validate \ --config path/to/config.yml \ --pipeline dnd-session ``` - Use only implemented production module keys listed in [Configuration](config.md#implemented-production-modules). - Check that artifact lanes include an `extract` binding. ## Invalid `--only` Symptoms include: - `--only must contain comma-separated non-empty artifact lane IDs` - `--only requires --pipeline` - `selected artifact lane` Fix: - Use comma-separated lane IDs with no empty entries: ```sh go run ./cmd/notarius run dnd-session \ --config path/to/config.yml \ --input path/to/input.json \ --only spells ``` - For `config validate`, include `--pipeline` when using `--only`. - Confirm the lane ID exists under `pipelines..artifacts`. ## Reference Binding Failure Symptoms include: - `reference slot "..." is not declared` - `reference slot "..." is declared by multiple selected targets` - `required reference slot "..." is not bound` - `--reference must use slot=path` - `--without-reference must use a reference selector without =path` - `read "...": no such file` - `must be UTF-8 text` - `media type "..." is not accepted` - `is ... bytes, limit ...` Fix: - Confirm the selected chunker, extractor, merger, or normalizer declares the slot. The implemented `dnd/scenes` chunker and `dnd/spells` extractor declare optional `players`, `party`, and `glossary` slots, plus `roster` as a deprecated compatibility alias for `party`. - Use a specific selector when more than one selected target declares the same slot: `chunk.context=./context.txt`, `spells.extract.context=./extract-context.txt`, `spells.merge.context=./merge-context.txt`, or `spells.normalize.context=./normalize-context.txt`. - `lane.slot=path` is valid only when exactly one selected extractor, merger, or normalizer in that lane declares the slot. If more than one does, use `lane.extract.slot=path`, `lane.merge.slot=path`, or `lane.normalize.slot=path`. - Use `--without-reference selector` to remove optional config bindings; do not pass an empty `--reference selector=`. - Check whether a path came from config or CLI. Config paths are relative to the config file. CLI reference paths are relative to the current working directory. - Ensure the file is readable UTF-8 text and within any byte limit declared by the declaring module. - If the declaring module narrows accepted media types, use a file extension that infers an accepted type such as `text/markdown`, `application/yaml`, or `application/json`. Unknown extensions infer `application/octet-stream`. - If diagnostics are retained, inspect `resolved-pipeline.json`, `resolved-references.json`, and `error.log`. ## Seriatim Input Validation Failure Symptoms include `seriatim input`, `parse JSON`, `segments must not be empty`, or validation errors naming a segment field. Fix: - Compare the input to [examples/seriatim-minimal-transcript.json](../examples/seriatim-minimal-transcript.json). - Ensure the JSON has a `metadata` object and a non-empty `segments` array. - Each segment needs a non-empty `id`, non-empty `speaker`, non-empty `text`, non-negative numeric `start`, and non-negative numeric `end`. - Segment IDs must be unique and must not contain leading or trailing whitespace. - `end` must be greater than or equal to `start`. ## Scriptorium Profile Source Failure Symptoms include: - `scriptorium profile_dir and profile_file are mutually exclusive` - `scriptorium.profile_dir must not be empty when set` - `scriptorium.profile_file must not be empty when set` - `profile load` - `profile not found` Fix: - Configure at most one of `scriptorium.profile_dir` or `scriptorium.profile_file`. - Confirm the selected Scriptorium profile ID exists in the configured profile source or Scriptorium built-in profiles. - If using `--llm-profile`, pass a Scriptorium profile ID, not a removed Notarius profile ID. - Validate the config and selected pipeline: ```sh go run ./cmd/notarius config validate \ --config path/to/config.yml \ --pipeline dnd-session ``` ## LLM Profile Override Failure Symptom: ```text notarius: LLM profile override "..." is not configured ``` Fix: - Add the profile to the configured Scriptorium profile source. - Or use an existing Scriptorium profile ID with `--llm-profile`. Use `--llm-profile ` when one run should force every LLM-backed binding to the same Scriptorium profile. The override applies to effective chunk, extract, merge, and normalize bindings. ## Missing API Key Environment Variable Symptoms include: - `api_key_env` - `unset environment variable` - provider authentication failures after selecting a profile that needs a key Fix: - Check the selected Scriptorium profile's `api_key_env` field. - Set that environment variable before running Notarius. - Do not put raw API keys in Notarius config or file-backed Scriptorium profiles. ## Prompt Or Structured Output Failure Symptoms include: - `prompt not found` - `prompt render` - `schema` - `validation` - `decode structured output` Fix: - Ensure production modules register their embedded Scriptorium prompt and schema assets. - If the error names a profile, select a Scriptorium profile that is available through the configured profile source or built-in catalog. - If the error names generated output validation, retry with a model that follows JSON schema instructions reliably. - Inspect retained diagnostics `error.log`, `resolved-pipeline.json`, and `run-manifest.json` when available. Prompt text, source text, reference content, raw schema JSON, and secrets are not written to default diagnostics. - Provider errors are redacted for bearer tokens and configured API key values. ## Scene Chunking Failure Symptoms include: - `dnd scenes chunker` - `malformed structured output` - `boundary_caveats` - `start_unit_id` - `end_unit_id` - `gap` - `overlap` - `final scene` - `complete structured output` Fix: - Validate the pipeline configuration and confirm the input module provides a transcript source when using `chunk: dnd/scenes`. - Confirm the selected Scriptorium profile has a working endpoint, model, and credentials. - Inspect retained diagnostics for the run error and resolved pipeline. - If the error names malformed structured output, retry with a model that follows structured response schemas reliably. - If the error names `boundary_caveats`, check for blank or whitespace-only caveat text in the scene response. - Scene boundaries must resolve to valid source units, cover the full source document, be contiguous, and not overlap. ## Session ID Symptom: external logs or provider traces cannot be correlated with a Notarius run. Fix: - Pass `--session-id ` to `notarius run`. - Use a stable, non-secret identifier from the external orchestrator. ## Resume Or Checkpoint Reuse Failure Symptoms include: - `--resume requires workspace.resume.enabled: true` - `checkpoint artifact is missing` - `checkpoint workspace schema version` - `checkpoint dependency fingerprints do not match` - a resumed run executes work instead of reusing a checkpoint Fix: - Set both `workspace.directory` and `workspace.resume.enabled: true`. - Use `--resume`; plain `notarius run` executes normally and refreshes checkpoints. - Confirm the current run uses the same input bytes, resolved pipeline, selected lanes, runtime LLM profile override, and materialized references as the run that wrote the checkpoint. - Inspect retained diagnostics `checkpoint-events.json` to see which workflow steps were reused or executed. - If a checkpoint payload is missing or corrupt, rerun without relying on that checkpoint. Notarius executes invalidated steps normally and writes fresh checkpoints when checkpointing remains enabled. Checkpoint files can contain source text, intermediate outputs, rejected outputs, metadata, and warnings. Protect the workspace directory accordingly. ## Debug Output Missing Or Too Verbose Symptoms: - no files appear under `/debug//`; - debug files contain more source, reference, prompt, or model-output material than expected. Fix: - Set both `workspace.directory` and `workspace.debug.enabled: true`. - Confirm you are inspecting the current run ID. Debug output is per invocation and is not used for resume. - Disable `workspace.debug.enabled` after the inspection run. Debug output may contain sensitive source material, reference material, prompt inputs, model outputs, and validation payloads. ## Output Write Failure Symptoms include: - `create output directory` - `write output file` - `output file name must` - `unsupported media type` - `invalid JSON` Fix: - Ensure `--output-dir` points to a directory path or a path that can be created. - Check filesystem permissions and available disk space. - The production JSON output encoder writes lane payloads under `lanes/` and accepts only valid `application/json` normalized outputs. If an error names an unsupported media type or invalid JSON, inspect the lane's merge and normalize module output. - If diagnostics were retained, inspect `run-report.json`, `run-manifest.json`, and `error.log`. The CLI rejects unsafe logical output paths before writing files. ## Raw Output Rejection Symptoms include a successful run with: - `validation_status` set to `rejected`; - non-empty `rejected.json`; - `rejected_outputs` entries in `manifest.json`. Explanation and fixes: - Validator rejection is a non-fatal run outcome. Rejected module outputs do not pass to the next pipeline stage. - Check `rejected.json` for the stage, lane, module, chunk, validator, reason, message, and attempt count. - Check `manifest.json` `validator_chains` to see the exact resolved validators and order used for the rejected validation point. The production `dnd/spells` extractor runs JSON syntax, JSON schema, D&D spell shape, source-reference, and source-relatedness validators by default. - If the configured chain is not what you expected, inspect the selected binding in config. Omitted `validators` uses production defaults, `validators: []` disables validators for that binding, and a non-empty list replaces the default chain in configured order. - Run `notarius config validate --pipeline ` to catch unknown validator keys and invalid validator `llm_profile` usage before running the pipeline. - Increase a module binding's `retries` only when re-running the same module input can reasonably produce an acceptable output. - If rejection is deterministic, fix the source input, module configuration, or validation policy rather than adding retries. Common production D&D spell validator reasons: - `invalid_json`: the raw output is not valid JSON. - `json_schema_invalid`: the raw JSON does not match the spell response schema. - `invalid_spell_shape`: required spell-cast fields are missing or malformed. - `invalid_source_refs`: source references are missing or do not point to valid source units. - `spell_not_near_source`: warning-only; the spell name was not found near the cited source text. ## Retry Exhaustion Symptoms include: - errors containing `failed after ... attempt(s)`; - rejected output records with `attempt_count` greater than `1`. Fix: - `retries` is the number of extra attempts after the first attempt for chunk, extract, merge, and normalize bindings. - Framework-level errors after the last attempt fail the run. - Validator rejections after the last attempt are recorded as rejected outputs. - Check retained `error.log`, `run-manifest.json`, and `rejected.json` for the operation, module key, lane, chunk, and attempt count. ## Diagnostics Directory Surprise Symptom: the diagnostics directory is missing after a successful run. Fix: - Check `diagnostics.retention`. - With `auto`, successful runs without warnings are removed. - Use `diagnostics.retention: always` when every diagnostics run directory should be kept. - Use `--diagnostics-dir` to override the configured work directory for a run. Symptom: diagnostics exist even with `retention: never`. Explanation: - Failed runs are retained so that `error.log` and available context can be inspected.