notarius/docs/troubleshooting.md

Troubleshooting

This guide maps common implemented failure modes to inspection steps and fixes. For command syntax, see CLI Reference. For YAML fields and environment overrides, see Configuration. For output and diagnostics layout, see Operations.

Config File Not Found

Symptom:

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 <name> not found
• total LLM concurrency must be greater than zero
• diagnostics retention "<value>" is not supported

Fix:

• Use version: 2.
• Remove unknown YAML fields.
• Validate with:

go run ./cmd/notarius config validate --config path/to/config.yml

Unknown Pipeline

Symptom:

notarius: pipeline "..." is not configured

Fix:

• List configured pipeline IDs:

go run ./cmd/notarius pipelines list --config path/to/config.yml

• Use one of those IDs in notarius run <pipeline-id>.
• 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:

go run ./cmd/notarius config validate \
  --config path/to/config.yml \
  --pipeline dnd-session

• Use only implemented production module keys listed in Configuration.
• 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:

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.<id>.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 roster and glossary slots.
• 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.
• 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:

go run ./cmd/notarius config validate \
  --config path/to/config.yml \
  --pipeline dnd-session

LLM Profile Override Failure

Symptom:

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 <id> 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 <id> to notarius run.
• Use a stable, non-secret identifier from the external orchestrator.

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

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.