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

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

```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.<id>.artifacts`.

## Reference Binding Failure

Symptoms include:

- `reference slot "..." is not declared`
- `reference slot "..." is declared by multiple selected lanes`
- `required reference slot "..." is not bound`
- `--reference must use slot=path or lane.slot=path`
- `--without-reference must use slot or lane.slot`
- `read "...": no such file`
- `must be UTF-8 text`
- `media type "..." is not accepted`
- `is ... bytes, limit ...`

Fix:

- Confirm the selected extractor declares the slot. The implemented
  `dnd/spells` extractor declares optional `roster` and `glossary` slots.
- Use `lane.slot=path` when more than one selected lane declares the same slot.
- Use `--without-reference slot` to remove optional config bindings; do not pass
  an empty `--reference slot=`.
- 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 extractor.
- If the extractor narrows accepted media types, use a file extension that
  infers an accepted type such as `text/markdown` 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`.

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

```text
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`
- `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 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.
- If the error names `boundary_caveats`, check for blank or whitespace-only
  caveat text in the scene response.
- 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.