Repository navigation
Technical Troubleshooting
Audience: advanced administrators, developers and AI-assisted support. Baseline reviewed: 2026-10-29.
Record the user's goal, actual result, component versions, entry route/action, safe resource/job identifiers and timestamp/time zone. Identify whether the issue is reproducible, intermittent or already present before a deployment. Preserve relevant source and deployment differences.
Do not begin with a restart or cleanup. A site can share databases, encoders, live services, storage and containers with other independent installations. Read-only evidence should establish the affected boundary first.
| Symptom | First evidence | Next distinction |
|---|---|---|
| JSON action fails | Actual status, response body and application log | Routing/bootstrap, authentication, validation or business-state failure |
| Video is listed but will not play | Generated source URL and browser media requests | Metadata exists vs. real object/playlist/segment/key availability |
| Encoder appears done but video is unavailable | Job, transfer and completion callback | Converted output vs. transfer, hooks/storage and publication |
| Seek previews are missing | VideoThumbnails worker/log and saved sprite | Placeholder, generation failure, locked/rate-limited worker or save/delivery failure |
| Live is visible but cannot be watched | Session, stats, HLS chain and player | Ingest success vs. conversion/delivery/client failure |
| One restream target fails | That destination's process/log and remote state | Startup retry, midstream interruption or source-end behavior |
| Recording is incomplete/missing | Physical files and publish/record events | Recording controls vs. finalization, conversion and storage |
| Payment succeeded but access is absent | Provider, checkout, wallet and entitlement | Credit vs. fulfillment or a retryable reconciliation issue |
| Saved value is not reflected | Database state and specific cache layer | Failed write vs. cached read or delayed invalidation |
| Notifications/jobs stop | Owner cron, locks and queue/progress state | Disabled scheduling vs. slow/failed worker or transport/provider problem |
Use the actual application log destination and component-specific logs. Align host/database/application/provider times. Track a job or session through the chain instead of collecting unrelated errors from the same day.
Preserve credentials, session cookies, stream keys, signed media URLs and payment secrets. Report safe identifiers and redacted context. Installation configuration is not a documentation fixture.
- A configuration/lint check proves syntax, not successful operation.
- HTTP 200 proves a transport response, not successful payment, conversion or playback.
- A running FFmpeg process proves local execution, not successful destination viewing.
- A container/media probe validates structure/packets, not a full audiovisual review.
- A local placeholder can represent a healthy remote object.
- A completed transfer does not establish a restorable backup.
Use relevant unit/regression checks plus a real integration test when the affected workflow requires it. Mark unavailable authenticated, provider, destination and end-to-end checks explicitly.
State the affected resource/session/job, baseline, concrete observations, interpretation, uncertainties and next verification. Separate pre-existing failures from regressions. Inspection does not authorize service restarts, package changes, destructive cleanup or production table deletion.
