117 lines
5.6 KiB
Markdown
117 lines
5.6 KiB
Markdown
# 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](cli.md)
|
|
- Configuration reference: [config.md](config.md)
|
|
- Operations guide: [operations.md](operations.md)
|