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, --format is required, or exactly one of --keep or --remove is required.
• Likely cause: one or more required flags were omitted.
• Inspection: run help for the failing command:
  • go run ./cmd/seriatim merge --help
  • go run ./cmd/seriatim trim --help
  • go run ./cmd/seriatim normalize --help
  • go run ./cmd/seriatim render --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 the target path is unusable.
• Inspection: verify parent path and permissions:
  • dirname <path>
  • ls -ld <parent-dir>
• Safe fix: create or fix the parent directory and rerun. Use a file path (not a directory path) for output/report 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 JSON and required segment fields (start, end, text):
  • jq . <input-file>
• Safe fix: correct 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 render input artifact

• Symptom: render fails with messages like input JSON is malformed or input JSON is not a valid seriatim output artifact.
• Likely cause: input is malformed JSON or not one of the supported seriatim output schemas.
• Inspection:
  • jq . <input-file>
  • compare input shape against schema/minimal-output.schema.json, schema/intermediate-output.schema.json, and schema/full-output.schema.json
• Safe fix: render only a valid existing seriatim artifact (seriatim-minimal, seriatim-intermediate, or seriatim-full).

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 contract.
• 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 format or schema values

• Symptom:
  • render: --format must be "markdown"
  • merge/normalize/trim: --output-schema must be one of ...
• Likely cause: unsupported --format or --output-schema value.
• Inspection:
  • command flags
  • echo "$SERIATIM_OUTPUT_SCHEMA" (for merge/normalize defaults)
• Safe fix:
  • render: use --format markdown
  • output schema: use 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.

Artifact or schema validation failures

• Symptom: errors such as validate-output: ..., input JSON is not a valid seriatim output artifact, or related schema-validation errors.
• Likely cause:
  • merge module order/config produced an invalid output artifact, or
  • trim/render input is not a valid seriatim output artifact.
• Inspection:
  • for merge: inspect customized module ordering flags
  • for trim/render: validate input against schema files in schema/
• Safe fix:
  • merge: restore a valid postprocessing order ending with assigned IDs before output validation
  • trim/render: provide a valid seriatim artifact as 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 points to an invalid target.
• 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