Common Errors Catalog & Remediation Reference
This catalog provides an immediate lookup table for runtime error messages, log warnings, and HTTP status codes emitted by RUSEON Core.
Error Lookup Matrix
| Error Message / Code | Subsystem | Root Cause | Remediation Steps |
|---|---|---|---|
401 Unauthorized: token has expired | Authentication | The client's JWT token has exceeded its configured lifetime | Refresh the JWT token using /api/v1/auth/refresh or re-authenticate via /api/v1/auth/login. |
403 Forbidden: insufficient role permissions | RBAC | Current user role does not have permission for the requested action | Ensure the user account has operator or admin privileges assigned. |
404 Not Found: camera not registered or inactive | REST / Stream | Requested camera ID does not exist in BadgerDB or is currently disabled | Verify camera ID with GET /api/v1/cameras or add camera via Web UI / CLI. |
503 Service Unavailable: database / storage not ready | Probes | Storage volume is unmounted, read-only, or BadgerDB is recovering | Check /readyz response, inspect disk write permissions and mount state. |
bind: address already in use | Network | Port 8080, 8554, or 9090 is already bound by another process | Find conflicting process with sudo lsof -i :8080 or change port in config.yaml. |
badger: lock file is already acquired | Storage | Another RUSEON instance or CLI tool is currently using /app/data/db | Ensure only one server process accesses the database directory simultaneously. |
RTSP DESCRIBE failed: 401 Unauthorized | Camera Ingest | Camera RTSP credentials in the URL are missing, incorrect, or expired | Update RTSP username and password in camera settings. URL-encode special characters. |
WebRTC ICE connection failed | WebRTC | UDP media packets blocked by firewall or client received private IP | Set webrtc.public_ip in config.yaml and open UDP ports 50000-50100. |
Slow consumer detected, skipping P-frame | Ring Buffer | A viewer's network connection or disk writer is lagging behind ingest | Non-fatal warning. The buffer drops P-frames to protect server pipeline stability. |
write /data/recordings: no space left on device | Archiver | Disk partition is 100% full | Ensure recording.retention_days and min_disk_free_gb are configured properly. |
Diagnostic CLI Commands
bash
# Check overall service status
ruseon-cli status
# Validate configuration syntax
ruseon-cli config validate -c /etc/ruseon/config.yaml
# Run database integrity check
ruseon-cli db verify
# Inspect live camera ingestion health
ruseon-cli cameras list