seriatim/docs/troubleshooting.md

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
• Configuration reference: config.md
• Operations guide: operations.md