114 lines
3.7 KiB
Markdown
114 lines
3.7 KiB
Markdown
|
# 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:
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"code": "BE-EXPORT-002",
|
||
|
|
"message": "FFmpeg export failed",
|
||
|
|
"requestId": "exp_20260415_001",
|
||
|
|
"context": {
|
||
|
|
"format": "mp4",
|
||
|
|
"mode": "reencode"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|