283 lines
8.2 KiB
Markdown
283 lines
8.2 KiB
Markdown
# 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 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, or normalizer declares the slot. The
|
|
implemented `dnd/spells` extractor declares optional `roster` and `glossary`
|
|
slots.
|
|
- Use a specific selector when more than one selected target declares the same
|
|
slot. Examples include `chunk.context=./context.txt`,
|
|
`spells.extract.context=./extract-context.txt`, and
|
|
`spells.normalize.context=./normalize-context.txt`.
|
|
- `lane.slot=path` is valid only when exactly one selected extractor or
|
|
normalizer in that lane declares the slot. If both do, use
|
|
`lane.extract.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` 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.
|