314 lines
8.9 KiB
Markdown
314 lines
8.9 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: 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 <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`.
|
|
|
|
## 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 <id>` when one run should force every LLM-backed binding to
|
|
the same Scriptorium profile.
|
|
|
|
## 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 use exact source-unit IDs, 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`
|
|
|
|
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.
|