Troubleshooting bunqueue: Common Issues & Fixes

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

SandboxedWorker is experimental

SandboxedWorker depends on Bun Workers, which are experimental. Known issues include memory growth, thread duplication, and segfaults across Bun versions.

For production, use the standard Worker instead — it provides the same API (events, concurrency, heartbeats, retries) without any experimental dependencies. See Worker vs SandboxedWorker.

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.

Symptoms:

• Segmentation fault at address 0xE8
• Worker has been terminated errors
• Crashes during worker.terminate() calls
• Unexpected memory growth or thread duplication (#52)

Solution: Switch to the standard Worker for production workloads:

// ❌ SandboxedWorker — experimental, may crash
const worker = new SandboxedWorker('queue', {
  processor: './processor.ts',
  concurrency: 4,
});

// ✅ Worker — stable, production-ready, same functionality
const worker = new Worker('queue', async (job) => {
  // same logic from your processor.ts
  return result;
}, { embedded: true, concurrency: 4 });

If you must use SandboxedWorker:

• Pin your Bun version — behavior varies across releases
• Use graceful shutdown (await worker.stop()) instead of force termination
• Use longer timeout values to avoid frequent terminations
• Monitor memory usage closely

These issues will be resolved when Bun stabilizes their Worker API.

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

Related Guides

• Monitoring & Prometheus Metrics - Set up monitoring to prevent issues
• FAQ - Frequently asked questions
• Stall Detection & Recovery - Debug stalled jobs