TalkEdit/docs/runbooks/error-codes.md

Error Codes Runbook

Purpose: provide consistent, AI-readable error categories for faster autonomous debugging.

Format

Use codes in this format: <SUBSYSTEM>-<CATEGORY>-<ID>

Examples:

• BE-EXPORT-001
• FE-WAVEFORM-002
• HOST-BRIDGE-003

Backend (FastAPI / Services)

Export

• BE-EXPORT-001: Export request validation failed.

  • Symptoms: HTTP 400, missing/invalid ranges.
  • Likely causes: malformed payload, empty segments.
  • First checks: request body shape, keep/mute/gain ranges.

• BE-EXPORT-002: FFmpeg command failed.

  • Symptoms: HTTP 500, stderr contains filter/codec error.
  • Likely causes: invalid filter chain, unsupported codec/container.
  • First checks: generated FFmpeg args, source media codec, target format.

• BE-EXPORT-003: Caption burn-in/subtitle generation failed.

  • Symptoms: burn-in export fails while plain export works.
  • Likely causes: ASS generation issue, subtitle path/temp file cleanup race.
  • First checks: ASS file generation, temp file lifecycle.

Transcription

• BE-TRANSCRIBE-001: Model unavailable or download failure.

  • Symptoms: transcription never starts or exits early.
  • Likely causes: missing model, network/cache issue.
  • First checks: model cache path, ensure-model logs.

• BE-TRANSCRIBE-002: Inference pipeline runtime failure.

  • Symptoms: mid-run crash, partial output.
  • Likely causes: CUDA/CPU mismatch, unsupported media, resource exhaustion.
  • First checks: environment, GPU availability, media decoding logs.

Audio / Waveform

• BE-AUDIO-001: Waveform endpoint failed.
  • Symptoms: waveform panel shows unavailable/error.
  • Likely causes: decode error, invalid file path, unsupported media input.
  • First checks: audio/waveform response body, file existence, FFmpeg decode path.

Frontend (React)

Timeline / Zones

• FE-TIMELINE-001: Zone interaction state inconsistency.

  • Symptoms: cannot drag/select/delete zones predictably.
  • Likely causes: stale selection/editing state, hidden/selected mismatch.
  • First checks: zone mode flags, selectedZone state transitions.

• FE-TIMELINE-002: Visibility filter mismatch.

  • Symptoms: hidden zones still interactive or selected.
  • Likely causes: hit-testing ignores visibility flags.
  • First checks: hit-test filters and selected-zone reset logic.

Media UI

• FE-WAVEFORM-001: Waveform fetch failed.

  • Symptoms: warning banner with URL/error.
  • Likely causes: backend unavailable, bad path encoding, CORS/proxy issue.
  • First checks: backend health endpoint, waveform URL, network tab logs.

• FE-PROJECT-001: Project load mismatch.

  • Symptoms: loaded media/transcript differs from saved data.
  • Likely causes: schema drift, fallback URL mismatch.
  • First checks: project schema fields, loadVideo/loadProject URL parity.

Host / Bridge (Tauri)

• HOST-BRIDGE-001: Desktop API bridge unavailable.

  • Symptoms: open/save/transcribe actions no-op or throw.
  • Likely causes: bridge init error, host command mismatch.
  • First checks: bridge initialization, command names, runtime environment.

• HOST-WEBKIT-001: Linux WebKit startup/render regression.

  • Symptoms: noisy startup errors, UI load issues.
  • Likely causes: CSP/font regressions, unsupported protocol calls.
  • First checks: CSP config, remote font usage, bridge fallback behavior.

Logging Guidance

When raising errors, include:

1. Error code.
2. Human message.
3. Correlation/request id.
4. Relevant paths/ids (sanitized).
5. Suggested first-check hints.

Example structured payload:

{
  "code": "BE-EXPORT-002",
  "message": "FFmpeg export failed",
  "requestId": "exp_20260415_001",
  "context": {
    "format": "mp4",
    "mode": "reencode"
  }
}