Troubleshooting Guide

Solutions to common issues when using bunqueue.

Installation Issues

”bunqueue requires Bun runtime”

bunqueue only works with Bun, not Node.js.

# Check if Bun is installed
bun --version

# Install Bun if needed
curl -fsSL https://bun.sh/install | bash

Permission errors on install

# Try with sudo (not recommended)
sudo bun add bunqueue

# Better: fix npm permissions
mkdir ~/.bun
chown -R $(whoami) ~/.bun

Database Issues

”SQLITE_BUSY: database is locked”

Multiple processes trying to write simultaneously.

Solutions:

1. Use WAL mode (default in bunqueue)
2. Ensure only one server instance per database file
3. Use server mode for multi-process access

# Check for multiple processes
lsof ./data/queue.db

# Kill stale processes
pkill -f bunqueue

”SQLITE_CORRUPT: database disk image is malformed”

Database corruption, usually from crash during write.

Solutions:

1. Restore from S3 backup
2. Delete and recreate database (data loss)

# Restore from backup
bunqueue backup list
bunqueue backup restore <key> --force

# Or recreate (loses data)
rm ./data/queue.db*
bunqueue start

Database file keeps growing

SQLite doesn’t automatically reclaim space.

# Vacuum the database (run when server is stopped)
sqlite3 ./data/queue.db "VACUUM;"

# Enable auto-vacuum (before creating database)
sqlite3 ./data/queue.db "PRAGMA auto_vacuum = INCREMENTAL;"

Embedded Mode Issues

”Command timeout” error

error: Command timeout
      queue: "my-queue",
      context: "pull"

This error means your Worker is trying to connect to a TCP server instead of using embedded mode.

Solution: Add embedded: true to both Queue and Worker:

// WRONG - Worker defaults to TCP mode
const queue = new Queue('tasks', { embedded: true });
const worker = new Worker('tasks', processor); // Missing embedded: true!

// CORRECT - Both have embedded: true
const queue = new Queue('tasks', { embedded: true });
const worker = new Worker('tasks', processor, { embedded: true });

SQLite database not created

The database is only created when DATA_PATH is set.

Solution:

// Set DATA_PATH BEFORE importing bunqueue
import { mkdirSync } from 'fs';
mkdirSync('./data', { recursive: true });
process.env.DATA_PATH = './data/bunqueue.db';

// Then import
import { Queue, Worker } from 'bunqueue/client';

Note

Without DATA_PATH, bunqueue runs in-memory (no persistence across restarts).

Jobs not persisted across restarts

If you’re using multiple files, the Worker’s autorun: true (default) can cause the QueueManager to initialize before DATA_PATH is set.

Solution: Use autorun: false and start the worker manually:

queue.ts

const worker = new Worker('tasks', processor, {
  embedded: true,
  autorun: false,  // Don't start automatically
});

export function startWorker() {
  worker.run();
}

main.ts

process.env.DATA_PATH = './data/bunqueue.db';

import { startWorker } from './queue';
startWorker();  // Start after DATA_PATH is set

Job Processing Issues

Jobs stuck in “active” state

Worker crashed while processing.

Solutions:

1. Enable stall detection
2. Restart workers

queue.setStallConfig({
  enabled: true,
  stallInterval: 30000,
  maxStalls: 3,
});

Jobs not being processed

Check these:

1. Is the queue paused?
2. Is there a worker for this queue?
3. Is rate limiting blocking jobs?

// Check if paused
const isPaused = queue.isPaused();

// Check counts
const counts = queue.getJobCounts();
console.log(counts);

// Check rate limit
const config = queue.getRateLimit();

Jobs failing immediately

Check the error in failed event:

worker.on('failed', (job, error) => {
  console.error('Job failed:', error);
  console.error('Job data:', job.data);
  console.error('Attempts:', job.attemptsMade);
});

Memory usage keeps growing

Possible causes:

1. Jobs not being removed after completion
2. Too many jobs in DLQ
3. Memory leak in processor

// Enable removeOnComplete
await queue.add('task', data, {
  removeOnComplete: true,
});

// Purge old DLQ entries
queue.purgeDlq();

// Check for leaks in processor
worker.on('completed', () => {
  console.log('Memory:', process.memoryUsage().heapUsed);
});

Connection Issues

”Connection refused” to server

Server not running or wrong port.

# Check if server is running
ps aux | grep bunqueue

# Check listening ports
lsof -i :6789
lsof -i :6790

# Start server
bunqueue start

TCP connection drops

Network issues or server overload.

// Add reconnection logic
let client = createClient();

client.on('error', async () => {
  await sleep(1000);
  client = createClient();
});

Authentication failures

# Check token is set
echo $AUTH_TOKENS

# Test with curl
curl -H "Authorization: Bearer your-token" \
  http://localhost:6790/health

Performance Issues

Slow job processing

Optimize:

1. Increase worker concurrency
2. Use batch operations
3. Check database I/O

// Increase concurrency
const worker = new Worker('queue', processor, {
  concurrency: 20,
});

// Use bulk add
await queue.addBulk([...jobs]);

// Use bulk ack
await queue.ackBatch([...jobIds]);

High latency on pull

Check:

1. Index on queue table
2. Too many delayed jobs
3. Database on slow disk

-- Check indexes exist
.indices jobs

-- Check delayed jobs count
SELECT COUNT(*) FROM jobs WHERE state = 'delayed';

Server CPU at 100%

Too many connections or jobs.

# Check connection count
bunqueue stats

# Reduce polling frequency
# Add backoff in clients

Backup Issues

S3 backup failing

# Check credentials
echo $S3_ACCESS_KEY_ID
echo $S3_BUCKET

# Test connectivity
aws s3 ls s3://$S3_BUCKET/

# Check logs
bunqueue backup status

Restore failing

# List available backups
bunqueue backup list

# Force restore (overwrites existing)
bunqueue backup restore <key> --force

Sandboxed Worker Issues

Segmentation fault when terminating workers

If you experience crashes (segfaults) when using SandboxedWorker, especially during worker timeout or error handling, this is a known Bun bug.

Bun Worker API is experimental

From Bun’s documentation:

The Worker API is still experimental (particularly for terminating workers). We are actively working on improving this.

Symptoms:

• Segmentation fault at address 0xE8
• Worker has been terminated errors
• Crashes during worker.terminate() calls

Workaround:

• Avoid forcefully terminating workers when possible
• Use graceful shutdown instead of worker.terminate()
• Consider using the standard Worker class instead of SandboxedWorker for production workloads

// Instead of force termination
await worker.stop();  // Graceful shutdown

// Avoid tight timeout values that cause frequent terminations
const worker = new SandboxedWorker('queue', {
  processor: './processor.ts',
  timeout: 30000,  // Use longer timeout to avoid frequent terminations
});

This issue will be resolved in a future Bun release.

Common Error Messages

Error	Cause	Solution
Command timeout	Worker missing embedded: true	Add embedded: true to Worker options
SQLITE_BUSY	Database locked	Use single writer
SQLITE_FULL	Disk full	Free disk space
ECONNREFUSED	Server not running	Start server or use embedded mode
ETIMEDOUT	Network issue	Check connectivity
Job not found	Already completed/removed	Check job lifecycle
Segmentation fault	Bun Worker termination bug	Use graceful shutdown, see above

Debug Mode

Enable verbose logging:

# Server mode
LOG_FORMAT=json DEBUG=bunqueue:* bunqueue start

# Check logs
tail -f /var/log/bunqueue.log

Getting Help

If these solutions don’t help:

1. Check GitHub Issues
2. Search Discussions
3. Open a new issue with:
   • bunqueue version
   • Bun version
   • OS and hardware
   • Error message and stack trace
   • Minimal reproduction code