Skip to main content

​
Job Lifecycle

Every video goes through a multi-stage lifecycle from detection to completion. BitBonsai manages this automatically with zero user intervention required.
What is a job? A job is a single video file being encoded. Each video in your library becomes one job. See glossary for more details.
StatusDescriptionWhat Happens Next
DETECTEDFile found during library scanHealth check runs automatically
HEALTH_CHECKValidating file integrityMoves to NEEDS_DECISION or FAILED
NEEDS_DECISIONWaiting for user to queueUser selects codec and queues
QUEUEDWaiting for worker nodeStarts encoding when node available
TRANSFERRING(Multi-node only) Copying to workerStarts encoding after transfer
ENCODINGCurrently being encodedProgress updates in real-time
PAUSEDUser paused encodingResumes when user clicks Resume
VERIFYINGChecking output file healthMoves to COMPLETED or FAILED
COMPLETEDSuccessfully encodedOriginal backed up, file replaced
FAILEDEncoding error occurredAuto-retries 3x, then stops
CANCELLEDUser cancelled jobRemoved from queue

​
Lifecycle Flow Diagram

Most jobs go: DETECTED → HEALTH_CHECK → NEEDS_DECISION → QUEUED → ENCODING → VERIFYING → COMPLETED. The whole process is automatic after you click “Queue Selected.”

​
Job Status Details

​
DETECTED

  • What it means: File found during library scan
  • User action: None (automatic)
  • Duration: Milliseconds
  • Next step: Health check runs automatically

​
HEALTH_CHECK

  • What it means: BitBonsai is validating file integrity with FFmpeg
  • Checks performed:
    • File exists and is readable
    • Container format is valid (MP4, MKV, AVI, etc.)
    • Video/audio streams are decodable
    • Duration and metadata are accessible
    • No critical corruption in file structure
  • User action: None (automatic)
  • Duration: 1-5 seconds per file
  • Next step:
    • Healthy files → NEEDS_DECISION
    • Corrupted files → FAILED (not queued)
Health checks prevent encoding failures by detecting corrupt files before wasting CPU time. Failed health checks are logged with detailed error messages.

​
NEEDS_DECISION

  • What it means: File is healthy and ready to encode
  • User action: Select codec (HEVC/AV1) and click “Queue Selected”
  • Where to find: Libraries → Queue tab
  • Filters available:
    • Codec (find H.264 videos to upgrade)
    • Resolution (1080p, 4K, etc.)
    • Bitrate (target high-bitrate files)
    • File size (prioritize large files)

​
QUEUED

  • What it means: Job is waiting for an available worker node
  • User action: None (automatic)
  • Duration: Seconds to minutes (depends on queue depth)
  • Priority: First-in, first-out (FIFO)
  • Next step: Starts encoding when worker is free
Queue depth is visible in the Encoding tab header: “3 queued, 2 encoding”. Add more worker nodes to process queued jobs faster.

​
TRANSFERRING

  • What it means: (Multi-node only) File is being copied to worker node
  • User action: None (automatic)
  • Duration: Depends on network speed and file size
  • Why this happens: Some multi-node setups don’t use shared storage (NFS), so files must be transferred before encoding
  • Next step: Encoding starts after transfer completes
If you see many TRANSFERRING jobs, consider setting up NFS shared storage for instant zero-copy access. See Multi-Node Setup.

​
ENCODING

  • What it means: FFmpeg is actively encoding the video
  • User action: Monitor progress, or pause/cancel if needed
  • Duration: Minutes to hours (depends on codec, resolution, and hardware acceleration)
  • What you see:
    • Progress percentage (0-100%)
    • Estimated time remaining
    • Encoding speed (FPS)
    • Output file size estimate
    • Current vs. target bitrate

​
Progress Bar Breakdown

[████████████░░░░░░░░░░░░] 45% - 12:34 remaining
 │           │             │    └─ ETA based on current speed
 │           │             └─ Percentage complete
 │           └─ Empty portion (not yet encoded)
 └─ Filled portion (encoded)

​
Encoding Speed (FPS)

SpeedHardwareCodecNotes
5-15 FPSCPU (Intel i5)HEVCTypical for 1080p movies
20-40 FPSCPU (Intel i7/i9)HEVCFast encoding
40-80 FPSGPU (NVIDIA GTX 1660+)HEVCHardware acceleration
1-5 FPSCPUAV1Very slow but best quality
Slow encoding? Check Settings → Hardware Acceleration and enable NVIDIA/Intel/AMD GPU encoding if available. HEVC on GPU is 3-10x faster than CPU.

​
PAUSED

  • What it means: User manually paused encoding
  • User action: Click Resume to continue
  • Duration: Indefinite (until user resumes)
  • Progress saved: Yes, resumes from exact frame
  • Use case: Free up CPU/GPU for other tasks temporarily

​
VERIFYING

  • What it means: Encoded file is being validated for corruption
  • Checks performed:
    • Output file exists and is readable
    • FFprobe can parse container and streams
    • Duration matches original (within 2 seconds)
    • Video/audio streams are decodable
  • User action: None (automatic)
  • Duration: 1-3 seconds
  • Next step:
    • Healthy output → COMPLETED
    • Corrupted output → FAILED (re-queued for retry)
If verification fails repeatedly (3+ retries), the source file may be corrupted. Check the original file with ffprobe or VLC for playback issues.

​
COMPLETED

  • What it means: Encoding succeeded and file replaced
  • User action: None (automatic)
  • What happened:
    1. Original file backed up to /media/.bitbonsai/originals/[library]/[file]
    2. Encoded file replaces original in library
    3. Library metadata updated (new codec, bitrate, file size)
    4. Job marked complete and removed from active queue
  • File location: Same path as original (in-place replacement)
  • Backup location: [library-path]/.bitbonsai/originals/[relative-path]

​
File Size Comparison

Typical savings after encoding:
Original CodecTarget CodecFile Size Reduction
H.264 (1080p)HEVC40-50% smaller
H.264 (1080p)AV150-60% smaller
H.264 (4K)HEVC50-60% smaller
H.264 (4K)AV160-70% smaller
Example: A 10 GB H.264 movie encoded to HEVC becomes ~5 GB (50% savings). No quality loss with default CRF settings.

​
FAILED

  • What it means: Encoding encountered an error
  • User action:
    • Check error message in job details
    • Click Retry to manually retry
    • Auto-retries 3x before stopping
  • Common causes:
    • Corrupted source file (skip it)
    • Insufficient disk space (free up space)
    • FFmpeg crash (bug in codec)
    • Hardware encoder failure (try CPU fallback)
  • Auto-retry behavior:
    • 1st retry: Immediate
    • 2nd retry: 5 minutes later
    • 3rd retry: 15 minutes later
    • After 3 failures: Stops, requires manual retry

​
Error Categories

Error TypeCauseFix
Source CorruptedOriginal file unreadableSkip file or re-download
Disk FullNo space for output fileFree up space, job auto-retries
Codec ErrorFFmpeg crash or unsupported streamTry different codec (HEVC → AV1)
Hardware FailureGPU encoder crashDisable hardware acceleration in Settings
Permission DeniedDocker volume permissionsFix with chmod -R 777 /media
  1. Go to Encoding tab
  2. Filter by Failed status
  3. Click job row to expand details
  4. Error message shows FFmpeg output with:
    • Error category
    • Root cause analysis
    • Suggested fix
    • Full FFmpeg stderr log
Example error:
Error Category: SOURCE_CORRUPTED
Message: Invalid data found when processing input
Suggestion: Source file may be corrupted. Try re-downloading or skip this file.
FFmpeg stderr: [mov,mp4,m4a,3gp,3g2,mj2 @ 0x...] moov atom not found

​
CANCELLED

  • What it means: User manually cancelled encoding
  • User action: Job is removed from queue
  • Progress lost: Yes, cannot resume cancelled jobs
  • Use case: Queued wrong file or changed mind about codec

​
Job Details Panel

Click any job in the Encoding tab to view detailed information:
FieldDescription
Source FileFull file path in library
Target CodecHEVC (H.265), AV1, or VP9
ProgressPercentage complete (0-100%)
SpeedEncoding speed in FPS
Time RemainingETA based on current speed
Original SizeFile size before encoding
Output SizeEstimated file size after encoding
Original CodecSource codec (usually H.264)
ResolutionVideo resolution (1080p, 4K, etc.)
Original BitrateSource video bitrate (Mbps)
Target BitrateOutput video bitrate (Mbps)
Worker NodeWhich node is processing this job
Started AtWhen encoding began
Error Message(FAILED jobs only) FFmpeg error details
Pro tip: Sort jobs by “Time Remaining” to see which jobs finish soonest. Large 4K movies may take hours, while 1080p TV episodes finish in 5-10 minutes.

​
Retry Failed Jobs

​
Manual Retry

  1. Go to Encoding tab
  2. Filter by Failed status
  3. Select jobs to retry (checkbox or Select All)
  4. Click Retry Selected button
  5. Jobs move back to QUEUED and restart

​
Auto-Retry Behavior

BitBonsai automatically retries failed jobs 3 times with exponential backoff:
AttemptWait TimeNotes
1stImmediateRetry right away (transient errors)
2nd5 minutesWait before retry (disk space, network)
3rd15 minutesFinal retry before stopping
4th+Manual onlyRequires user intervention
Permanent failures (corrupted source files) retry 3 times and stop. Check error message to determine if file should be skipped.

​
Bulk Retry

Retry all failed jobs at once: 
# Select all failed jobs in UI
1. Filter by "Failed"
2. Click "Select All" (top left)
3. Click "Retry Selected"

​
Auto-Healing Features

BitBonsai includes multiple self-healing mechanisms to recover from errors automatically:

​
1. Orphaned Job Recovery (On Startup)

Problem: Container restarted mid-encoding → jobs stuck in ENCODING status Solution: On backend startup, BitBonsai finds all jobs with status ENCODING and resets them to QUEUED When it runs: Every backend container restart User action: None (automatic) Logs: 
🔄 Orphaned job recovery: Reset 3 stuck ENCODING jobs to QUEUED

​
2. Temp File Detection (NFS Mount Recovery)

Problem: NFS mount not ready → job marks file as “not found” → FAILED Solution: Before marking FAILED, retry 10 times with 2-second delays (20 seconds total) When it runs: During encoding temp file checks User action: None (automatic) Logs: 
🔄 Temp file not found, retrying (attempt 3/10)...
✓ Temp file detected after 6 seconds (NFS mount recovery)
This prevents false FAILED status during NFS mount hiccups or slow network storage.

​
3. Health Check Retry (Before Marking CORRUPTED)

Problem: Network hiccup during health check → false CORRUPTED status Solution: Retry health check 5 times with 2-second delays (10 seconds total) When it runs: During HEALTH_CHECK and VERIFYING stages User action: None (automatic) Why this matters: Prevents wasting time re-checking healthy files

​
4. CORRUPTED Auto-Re-Validation (Hourly)

Problem: Files marked CORRUPTED during NFS hiccups are often actually healthy Solution: Every hour, BitBonsai finds all CORRUPTED jobs and resets them to QUEUED for re-validation When it runs: Hourly (cron job in backend) User action: None (automatic) Logs: 
🔄 Auto-requeue: Found 12 CORRUPTED job(s) - resetting for re-validation
✓ Re-validated 12 jobs: 8 HEALTHY, 4 still CORRUPTED
Why hourly? NFS mounts often fail temporarily during network issues. Hourly re-checks catch files that become accessible again.

​
5. Stuck Job Watchdog (Detects Frozen Encodes)

Problem: FFmpeg crashes mid-encode but process doesn’t exit → job stuck at same progress for hours Solution: If progress hasn’t changed in 15 minutes, job is marked FAILED and auto-retried When it runs: Background watchdog every 5 minutes User action: None (automatic) Logs: 
⚠️ Stuck job detected: Job #123 at 45% for 20 minutes → FAILED (auto-retry)

​
Job History and Filtering

​
Filter Jobs by Status

The Encoding tab has a status filter dropdown:
FilterShows
ALLEvery job regardless of status
QUEUEDWaiting to start
ENCODINGCurrently in progress
COMPLETEDSuccessfully finished
FAILEDErrors (manual retry available)
CANCELLEDUser-cancelled jobs

​
Search Jobs

Use the search bar to find jobs by filename: 
Example: Search "Inception" finds:
- Inception.2010.1080p.BluRay.x264.mkv
- Inception (2010) - Director's Cut.mp4

​
Sort Jobs

Click column headers to sort:
ColumnSort By
File NameAlphabetical
ProgressPercentage (0-100%)
Time RemainingETA (soonest first)
SpeedFPS (fastest first)
StatusStatus order (QUEUED → ENCODING → …)
Quick wins: Sort by “Time Remaining” (ascending) to see which jobs finish soonest. Great for prioritizing short encodes.

​
Job History Retention

StatusRetention
COMPLETED30 days (configurable in Settings)
FAILED90 days (for debugging)
CANCELLED7 days
Completed jobs older than retention period are auto-deleted from database but files remain in library.

​
Troubleshooting

​
Job stuck in QUEUED

Symptom: Jobs stay in QUEUED for minutes/hours Possible causes:
  • All worker nodes offline (check Nodes page)
  • All nodes at max concurrency (add more nodes)
  • Database connection lost (check backend logs)
Fix:
  1. Go to Nodes page → check node status
  2. If offline: Restart worker node containers
  3. If online but idle: Check backend logs for errors
  4. If all busy: Wait for current jobs to finish or add nodes

​
Job stuck in ENCODING at 0%

Symptom: Job shows “Encoding” but progress stays at 0% Possible causes:
  • FFmpeg hasn’t written first progress line yet (wait 10-20 seconds)
  • FFmpeg crashed immediately (check logs)
  • Source file extremely large (4K HDR movies take time to start)
Fix:
  1. Wait 30 seconds (large files take time to initialize)
  2. Check backend logs: docker logs -f bitbonsai-backend
  3. If FFmpeg crashed: Error shows in logs, job auto-retries

​
Job failed with “Disk Full”

Symptom: Job fails with error “No space left on device” Fix:
  1. Free up disk space (delete old files, empty trash)
  2. Check available space: df -h /media
  3. Job auto-retries in 5 minutes (no manual action needed)
BitBonsai needs temporary space for encoding. Ensure at least 2x the largest file size is free on the volume.

​
Job failed with “Source Corrupted”

Symptom: Job fails immediately with “Invalid data found when processing input” Possible causes:
  • Original file is actually corrupted (download error, disk failure)
  • Unsupported codec or container format
  • Partial file (download not complete)
Fix:
  1. Test file in VLC or ffprobe: 
    ffprobe /path/to/file.mkv
  2. If file plays in VLC but fails FFprobe: Report bug (rare)
  3. If file doesn’t play: Re-download or skip this file

​
Completed job but file still H.264

Symptom: Job shows COMPLETED but file codec didn’t change Possible causes:
  • Original wasn’t replaced (backup failed)
  • Viewing cached metadata in file explorer (refresh)
Fix:
  1. Check file info: ffprobe /path/to/file.mkv
  2. Check backup exists: /media/.bitbonsai/originals/[file]
  3. If backup exists but file not replaced: Report bug