bullmq-queue-debug

name	bullmq-queue-debug
description	BullMQ job queue debugging for Volatio, redis-cli inspection patterns, checking stuck/failed/completed jobs, avoiding bun --eval hangs with queue connections. Use when jobs stuck, queue inspection needed, or debugging background workers.

bullmq-queue-debug

When to Use

• Jobs appear stuck or not processing
• Need to inspect queue state (waiting, completed, failed)
• Debugging background job workers
• Checking if jobs are being added correctly

Golden Path: Check Queue via Redis Directly

Never use bun --eval with BullMQ imports - it hangs because Redis connections don't close.

# Check waiting jobs
docker exec volatio-redis-1 redis-cli LLEN bull:news.yahoo-sync:wait

# Check completed jobs
docker exec volatio-redis-1 redis-cli ZCARD bull:news.yahoo-sync:completed

# Check failed jobs
docker exec volatio-redis-1 redis-cli ZCARD bull:news.yahoo-sync:failed

Common Queue Names

Queue	Pattern
Yahoo News Sync	bull:news.yahoo-sync:*
Economic Calendar	bull:calendar.sync:*

Redis Queue Key Patterns

# List all BullMQ keys
docker exec volatio-redis-1 redis-cli KEYS 'bull:*'

# Check specific queue lengths
docker exec volatio-redis-1 redis-cli LLEN bull:<queue-name>:wait
docker exec volatio-redis-1 redis-cli ZCARD bull:<queue-name>:completed
docker exec volatio-redis-1 redis-cli ZCARD bull:<queue-name>:failed
docker exec volatio-redis-1 redis-cli ZCARD bull:<queue-name>:delayed

Inspecting Job Data

# Get waiting job IDs
docker exec volatio-redis-1 redis-cli LRANGE bull:news.yahoo-sync:wait 0 10

# Get job data (replace <job-id>)
docker exec volatio-redis-1 redis-cli HGETALL bull:news.yahoo-sync:<job-id>

If You MUST Use TypeScript to Check Queues

Create a dedicated script file that explicitly closes connections:

// packages/jobs/src/scripts/check-queue-status.ts
import { yahooNewsSyncQueue } from '../domains/news/yahoo-sync.job';

async function main() {
  const job = await yahooNewsSyncQueue.getJob('yahoo-sync-2025-01-15');
  console.log('Status:', await job?.getState());
  console.log('Result:', job?.returnvalue);
  
  // CRITICAL: Close queue connection explicitly
  await yahooNewsSyncQueue.close();
}

main();

Then run:

bun run --env-file ../../.env packages/jobs/src/scripts/check-queue-status.ts 2>&1

Don'ts

Never Use bun --eval with BullMQ

# ❌ BAD: Hangs indefinitely
bun --eval "
import { yahooNewsSyncQueue } from './src/domains/news/yahoo-sync.job';
const job = await yahooNewsSyncQueue.getJob('job-id');
console.log(job?.returnvalue);
process.exit(0);  // Still hangs!
"

Why it hangs:

1. BullMQ maintains persistent Redis connections
2. process.exit(0) doesn't cleanly close connections
3. Multiple connections from eval scripts conflict with workers

Clearing Stuck Queues

# Remove all waiting jobs
docker exec volatio-redis-1 redis-cli DEL bull:news.yahoo-sync:wait

# Remove all failed jobs
docker exec volatio-redis-1 redis-cli DEL bull:news.yahoo-sync:failed

# Clear entire queue (nuclear option)
docker exec volatio-redis-1 redis-cli KEYS 'bull:news.yahoo-sync:*' | xargs docker exec volatio-redis-1 redis-cli DEL

Verify Redis is Running

docker compose ps | grep redis
docker exec volatio-redis-1 redis-cli PING  # Should return PONG