# Troubleshooting

Each entry includes symptom, likely cause, inspection step, and safe fix.

## Missing required flags

- Symptom: command fails with messages like `--input-file is required`, `--output-file is required`, or `exactly one of --keep or --remove is required`.
- Likely cause: required command flags were omitted.
- Inspection: run command help for the failing command:
  - `go run ./cmd/seriatim merge --help`
  - `go run ./cmd/seriatim trim --help`
  - `go run ./cmd/seriatim normalize --help`
- Safe fix: provide all required flags; for `trim`, provide exactly one selector mode (`--keep` or `--remove`).

## Invalid output or report path

- Symptom: errors like `--output-file parent directory ...` or `--report-file parent directory ...`.
- Likely cause: parent directory does not exist, is not a directory, or path points to an unusable target.
- Inspection: verify paths:
  - `dirname <path>`
  - `ls -ld <parent-dir>`
- Safe fix: create/fix the parent directory and rerun; avoid using directory paths directly as output/report file targets.

## Invalid merge input JSON

- Symptom: merge fails with messages like `parse input file`, `must contain top-level segments array`, `segment 0 missing numeric start`, or `segment 0 words must be an array`.
- Likely cause: malformed JSON or unsupported/missing fields in a merge input file.
- Inspection: validate input JSON and required fields (`start`, `end`, `text`):
  - `jq . <input-file>`
- Safe fix: correct the JSON structure and segment/word field types, then rerun `merge`.

## Invalid normalize input shape

- Symptom: normalize fails with messages like `must contain a "segments" field`, `"segments" must be an array`, or `top-level object with "segments" or a top-level segment array`.
- Likely cause: normalize input is neither supported object-with-segments nor top-level segment array.
- Inspection: inspect top-level JSON shape:
  - `jq 'type' <input-file>`
  - `jq 'keys' <input-file>` (for object input)
- Safe fix: reshape input into one supported form and rerun `normalize`.

## Invalid speaker map or autocorrect YAML

- Symptom: merge fails with errors such as `must contain at least one match rule`, `must include speaker`, `must include target`, or duplicate match/speaker validation failures.
- Likely cause: YAML rule file structure/content does not match expected schema.
- Inspection: check YAML validity and required top-level keys:
  - `speakers.yml` requires top-level `match` rules.
  - `autocorrect.yml` requires top-level `autocorrect` rules.
- Safe fix: correct YAML structure and rule content, then rerun `merge`.

## Unknown module names

- Symptom: errors like `unknown input reader`, `unknown preprocessing module`, `unknown postprocessing module`, or `unknown output module`.
- Likely cause: module name typo or unsupported module in flag lists.
- Inspection: compare provided module names against defaults in CLI help and config docs.
- Safe fix: use implemented module names only or remove unsupported modules from comma-separated lists.

## Invalid output schema value

- Symptom: errors like `--output-schema must be one of ...`.
- Likely cause: unsupported schema value from flag or `SERIATIM_OUTPUT_SCHEMA`.
- Inspection: check effective value:
  - command flags
  - `echo "$SERIATIM_OUTPUT_SCHEMA"`
- Safe fix: use one of `seriatim-minimal`, `seriatim-intermediate`, or `seriatim-full`.

## Invalid trim selector

- Symptom: trim fails with messages like `invalid selector ... malformed element`, `segment ID must be positive`, or descending-range errors.
- Likely cause: selector syntax is invalid.
- Inspection: verify selector format:
  - single ID: `7`
  - range: `1-10`
  - list: `1-10,15,20-25`
- Safe fix: correct selector syntax and rerun `trim`.

## Schema validation failures

- Symptom: errors such as `validate-output: ...` in merge or `input JSON is not a valid seriatim output artifact` in trim.
- Likely cause:
  - merge module order/config produced invalid final artifact (for example, validating before IDs are assigned), or
  - trim input is not a valid seriatim artifact.
- Inspection:
  - for merge: inspect customized module ordering flags.
  - for trim: verify input artifact against known seriatim schema files in `schema/`.
- Safe fix:
  - restore valid merge postprocessing order ending with assigned IDs before validation, or
  - provide a valid seriatim artifact as trim input.

## Report write failure

- Symptom: errors like `write --report-file ...` or file-create failures when report writing is requested.
- Likely cause: report path is not writable or is an invalid target (for example a directory path).
- Inspection:
  - `ls -ld <report-parent-dir>`
  - verify `--report-file` is a file path, not a directory
- Safe fix: choose a writable file path under an existing directory and rerun.

## Related docs

- CLI reference: [cli.md](cli.md)
- Configuration reference: [config.md](config.md)
- Operations guide: [operations.md](operations.md)