Bull Job Queue

Common errors

• Error: connect ECONNREFUSED 127.0.0.1:6379

  cause Bull failed to connect to the Redis server because it's not running or is inaccessible.
  fix Start your Redis server, check the Redis connection string (host, port) in your Bull configuration, and verify network access or firewall settings.

• UnhandledPromiseRejectionWarning: Error: Missing process handler for job type [jobType]

  cause A worker attempted to process a job type for which no `queue.process('jobType', ...)` handler has been defined.
  fix Ensure that your worker process calls `queue.process()` with a handler for every job type you expect to process. If you don't specify a type when adding a job, the default type is used, which also requires a handler.

• Error: This is not a valid Job ID

  cause An operation (e.g., `getJob`, `remove`, `promote`) was attempted with a job ID that does not exist or is no longer valid in the queue.
  fix Verify that the job ID is correct and that the job still exists in the queue (i.e., it hasn't been completed, failed, or removed) before attempting to interact with it.

• Error: Command failed: OOM command not allowed when used memory > 'maxmemory'.

  cause The Redis server has reached its configured `maxmemory` limit, preventing further data writes.
  fix Increase the `maxmemory` setting in your Redis configuration, reduce the amount of data stored in Redis, or scale your Redis instance. Consider offloading large job payloads to external storage.

Warnings

• gotcha Bull is currently in maintenance mode, receiving only bug fixes. For new features or if starting a new project, consider using BullMQ, which is a modern rewrite in TypeScript.
  Fix: For new projects, evaluate BullMQ. For existing Bull projects, continue with caution, knowing feature development is frozen.
• gotcha Bull requires a running Redis instance to function. Connection issues (e.g., `ECONNREFUSED`) are common if Redis is not accessible.
  Fix: Ensure your Redis server is running and accessible from your application. Verify the Redis connection string (host, port, password) is correct. Check firewall rules if applicable.
• gotcha Jobs added to a queue will not be processed unless a worker (a call to `queue.process()`) is actively listening for jobs on that queue.
  Fix: Ensure you have at least one worker process running `queue.process(callback)` for each queue you intend to process jobs from. If using job types, ensure a handler exists for each type.
• gotcha Job data stored in Bull is JSON-serialized. Complex objects (e.g., Date objects, custom class instances, functions) will lose their type or methods when serialized and deserialized.
  Fix: Pass only JSON-serializable data. For complex objects, convert them to a primitive representation before adding the job and reconstruct them within the worker, or store large/complex data externally and pass a reference (e.g., ID) in the job data.
• gotcha By default, Redis may not persist data to disk immediately. If your Redis server crashes without proper persistence configured (e.g., AOF or RDB snapshots), pending or delayed jobs might be lost.
  Fix: Configure Redis persistence (e.g., `appendonly yes` for AOF or `save` directives for RDB snapshots) to match your data durability requirements. Consult the Redis documentation for appropriate settings.

Install

• npm install bull npm
• yarn add bull yarn
• pnpm add bull pnpm

Imports

• Queue

  import { Queue } from 'bull';

  ESM is recommended for modern Node.js and TypeScript projects.
• Queue

  const { Queue } = require('bull');

  CommonJS is also fully supported.

Quickstart

Demonstrates creating a Bull queue, adding a job to it, and setting up a worker to process jobs from that queue. It also shows a basic event listener for job completion.

import { Queue } from 'bull';

const REDIS_URL = process.env.REDIS_URL ?? 'redis://127.0.0.1:6379';
const myQueue = new Queue('my-first-queue', REDIS_URL);

// Add a job to the queue
async function addJob() {
  const job = await myQueue.add({ foo: 'bar' });
  console.log(`Job ${job.id} added.`);
}

// Process jobs from the queue
myQueue.process(async (job) => {
  console.log(`Processing job ${job.id} with data:`, job.data);
  // Simulate async work
  await new Promise(resolve => setTimeout(resolve, 1000));
  console.log(`Job ${job.id} completed.`);
  return { status: 'success', processedAt: new Date() };
});

// Listen for global completed event (optional)
myQueue.on('global:completed', (jobId, result) => {
  console.log(`Job ${jobId} completed globally with result:`, JSON.parse(result));
});

// Call addJob to demonstrate
addJob().catch(console.error);