Skip to main content
BitBonsai is designed to self-heal from most issues, but occasionally you may need to intervene manually.
New to troubleshooting? Most issues are automatically fixed by BitBonsai’s auto-healing systems. See self-healing in the glossary.

​
Quick Diagnostics

Before diving into specific issues, run these commands to check system health: 
# Check Docker container status
docker compose ps

# Check backend logs
docker compose logs -f bitbonsai-backend

# Check database connectivity
docker compose exec postgres pg_isready -U bitbonsai

# Check disk space (see temporary files glossary entry)
df -h /path/to/temp /path/to/videos
Docker is the tool BitBonsai uses to run. Database stores job information. Temporary files are created during encoding.

​
Common Solutions

Stuck Jobs

Jobs stuck in ENCODING status after crash or restart

NFS Issues

Child nodes can’t access shared storage

Health Check Failures

Jobs marked CORRUPTED after encoding completes

Node Disconnected

Child node shows OFFLINE in UI

Frontend Errors

Web UI shows connection errors

Database Issues

Backend can’t connect to PostgreSQL

Disk Space

Encoding fails with “No space left on device”

Temp File Errors

Temp file not detected after multiple retries

​
Recovery & Debugging

Recovery Procedures

Full system reset, database backup/restore, reset stuck jobs

Advanced Debugging

Enable debug logging, monitor resources, network debugging