audita/docs/troubleshooting.md

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.