154 lines
4.2 KiB
Markdown
154 lines
4.2 KiB
Markdown
# Audita Troubleshooting
|
|
|
|
## Scope
|
|
|
|
This guide lists recurring implemented failure modes for `audita process` and `audita config`.
|
|
|
|
For each entry: symptom, likely cause, inspect, and fix.
|
|
|
|
## Config Validation Fails
|
|
|
|
Symptom:
|
|
- `audita config validate --config <path>` exits nonzero.
|
|
|
|
Likely causes:
|
|
- missing `version`;
|
|
- unsupported config version;
|
|
- unknown YAML field;
|
|
- unsupported module key or output schema;
|
|
- invalid numeric/range/concurrency/retention values.
|
|
|
|
Inspect:
|
|
1. rerun `audita config validate --config <path>` and read stderr.
|
|
2. if needed, inspect effective config with `audita config print-effective --config <path>`.
|
|
|
|
Fix:
|
|
- set `version: 1`;
|
|
- remove unknown fields;
|
|
- use supported module keys and output schemas (`bare-segments`, `audita-v1`);
|
|
- correct invalid values to satisfy validation constraints.
|
|
|
|
## Config File Resolution Errors
|
|
|
|
Symptom:
|
|
- `audita process` fails before processing with config-related errors like `config file not found`.
|
|
|
|
Likely causes:
|
|
- `--config` points to a missing path;
|
|
- `AUDITA_CONFIG` points to a missing path;
|
|
- unreadable config path.
|
|
|
|
Inspect:
|
|
1. confirm `--config` or `AUDITA_CONFIG` path exists;
|
|
2. run `audita config validate --config <path>` directly.
|
|
|
|
Fix:
|
|
- correct the path or unset invalid `AUDITA_CONFIG`;
|
|
- fix permissions for the config file.
|
|
|
|
## Transcript or Glossary Schema Errors
|
|
|
|
Symptom:
|
|
- stderr includes `transcript_schema` or `glossary_schema` and run exits nonzero.
|
|
|
|
Likely causes:
|
|
- transcript is not valid JSON or has invalid segment fields;
|
|
- glossary is not valid YAML or has missing required glossary entry fields.
|
|
|
|
Inspect:
|
|
1. check stderr for parser/validation details;
|
|
2. if diagnostics were created, inspect `error.log` and run `report.json` (`error_phase`);
|
|
3. inspect `source-transcript.json` and `source-transcript-parsed.json` in the run directory.
|
|
|
|
Fix:
|
|
- correct transcript JSON shape/content;
|
|
- correct glossary YAML shape/content and required entry fields;
|
|
- rerun validation with known-good tiny examples for comparison:
|
|
- `examples/tiny-transcript.json`
|
|
- `examples/tiny-glossary.yaml`
|
|
|
|
## LLM Runtime/Backend Failures
|
|
|
|
Symptom:
|
|
- stderr includes `runner_execution` (or backend timeout/error details) and nonzero exit.
|
|
|
|
Likely causes:
|
|
- unreachable/failed LLM endpoint;
|
|
- timeout/cancellation;
|
|
- runtime module execution failure.
|
|
|
|
Inspect:
|
|
1. inspect stderr for backend message details;
|
|
2. inspect run `report.json` (`error_phase`, `module_results`);
|
|
3. inspect diagnostics payloads and `error.log`.
|
|
|
|
Fix:
|
|
- verify model/base URL/API key settings;
|
|
- increase timeout if needed;
|
|
- rerun with `--work-dir-retention always` while debugging.
|
|
|
|
## Output File Write Failure
|
|
|
|
Symptom:
|
|
- stderr includes `failed to write output file` and run exits nonzero.
|
|
|
|
Likely causes:
|
|
- output path directory missing;
|
|
- insufficient filesystem permissions;
|
|
- invalid output target path.
|
|
|
|
Inspect:
|
|
1. check `--output` target directory exists and is writable;
|
|
2. inspect run diagnostics `error.log` and report `error_phase`.
|
|
|
|
Fix:
|
|
- write to a valid writable path;
|
|
- create missing directories;
|
|
- adjust permissions.
|
|
|
|
## Report File Write Failure
|
|
|
|
Symptom:
|
|
- stderr includes `failed to write report JSON file` and run exits nonzero.
|
|
|
|
Likely causes:
|
|
- invalid or unwritable `--report-json` target path.
|
|
|
|
Inspect:
|
|
1. verify parent directory exists and is writable;
|
|
2. inspect diagnostics `error.log` for `report_write` context.
|
|
|
|
Fix:
|
|
- choose a writable report path;
|
|
- create missing directories;
|
|
- rerun.
|
|
|
|
## Unsupported Output Schema
|
|
|
|
Symptom:
|
|
- stderr includes `unsupported output schema` and run exits nonzero.
|
|
|
|
Likely causes:
|
|
- unsupported `--output-schema` value;
|
|
- unsupported `output.schema` in config.
|
|
|
|
Inspect:
|
|
1. check CLI/config schema key;
|
|
2. run `audita config validate --config <path>` when config is involved.
|
|
|
|
Fix:
|
|
- use `bare-segments` or `audita-v1`.
|
|
|
|
## Diagnostics Directory Lookup
|
|
|
|
Symptom:
|
|
- run fails and you need artifacts for debugging.
|
|
|
|
Inspect:
|
|
1. read stderr for `audita process: diagnostics: <run-dir>`;
|
|
2. open `<run-dir>/report.json` and `<run-dir>/error.log`;
|
|
3. use diagnostics paths embedded in report metadata for artifact lookup.
|
|
|
|
Fix:
|
|
- rerun with `--work-dir-retention always` to preserve run directories during investigation.
|