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

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.

Missing LLM Base URL Or Model

Symptoms include:

• LLM profile "default" base URL must not be empty
• LLM profile "default" model must not be empty
• base URL must be valid

Fix:

• Set base_url and model in llm_profiles.default.
• Or set NOTARIUS_LLM_DEFAULT_BASE_URL and NOTARIUS_LLM_DEFAULT_MODEL.
• If a profile needs authentication, set api_key_env in YAML or set NOTARIUS_LLM_DEFAULT_API_KEY.

LLM Profile Override Failure

Symptom:

notarius: LLM profile override "..." is not configured

Fix:

• Add the profile under llm_profiles.
• Or use an existing profile ID with --llm-profile.

Current runs require exactly one distinct effective LLM profile. If a pipeline uses several profiles, run with --llm-profile <id> or align the bindings in configuration.

Provider HTTP Or Response Failure

Symptoms include:

• provider request failed
• provider returned status 400
• provider returned status 403
• provider response missing choices
• provider response assistant message content is not valid JSON
• decode structured output

Fix:

• Confirm the base_url points to an OpenAI-compatible endpoint root. Notarius posts to <base_url>/chat/completions.
• Check model and provider credentials.
• Inspect the retained diagnostics error.log.
• For 400 and 403 responses, fix the request configuration or credentials.
• For 429 and 5xx responses, the client retries according to max_retries; if the failure persists, inspect the provider response and adjust capacity, credentials, or model settings.
• The assistant message content must decode as JSON matching the extractor's structured response schema.

Provider error messages are redacted for configured API key values.

Scene Chunking Failure

Symptoms include:

• dnd scenes chunker
• malformed structured output
• 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 LLM profile has a working OpenAI-compatible base_url, 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.
• Scene boundaries must use exact source-unit IDs, cover the full source document, be contiguous, and not overlap.

Output Write Failure

Symptoms include:

• create output directory
• write output file
• output file name must

Fix:

• Ensure --output-dir points to a directory path or a path that can be created.
• Check filesystem permissions and available disk space.
• If diagnostics were retained, inspect run-report.json, run-manifest.json, and error.log.

The CLI rejects unsafe logical output paths before writing files.

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.