Registry / workflow / bull
library0.4.1jsnpmunverified

Bull is a battle-tested, Redis-backed job manager for Node.js, designed to handle background tasks, deferred processes, and distributed workloads with a strong emphasis on stability and atomicity. The current stable version is 4.16.5. As of recent updates, the project is in 'maintenance mode,' meaning it primarily receives bug fixes and security updates, with new feature development largely ceasing. Its release cadence is irregular, driven by necessary patches for critical issues like CVEs (e.g., cron-parser) and runtime errors (e.g., msgpackr buffer issues). Bull distinguishes itself through its robust, polling-free design for minimal CPU usage and reliable 'at least once' job processing semantics. For new projects and active feature development, users are strongly encouraged to consider BullMQ, which is a modern rewrite in TypeScript and the actively maintained successor.

npm install bull
INSTALL
IMPORT
SIG · BULL
B
bull
workflowjavascriptv0.4.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Queue
import Queue from 'bull';
const Queue = require('bull');
While `require` works for CommonJS, modern Node.js applications and TypeScript projects should use ES module `import` syntax.
Job
import { Job } from 'bull';
import Job from 'bull';
`Job` is typically used as a type or an interface for job processors and is a named export, not a default export. For direct usage or type annotation, it must be destructured.
QueueEvents
import { QueueEvents } from 'bull';
For listening to global queue events (e.g., 'completed', 'failed'), `QueueEvents` provides a dedicated interface, though direct event listeners on the `Queue` instance are also possible. For BullMQ, `QueueEvents` is a separate class.

This quickstart demonstrates how to create a Bull queue, add a job with options like retries and delays, and set up a worker to process jobs asynchronously. It also includes basic event listeners for job completion and failure, and a graceful shutdown mechanism.

import Queue from 'bull'; import IORedis from 'ioredis'; // Ensure a Redis server is running at localhost:6379 or configure as needed. // For production, always use robust Redis connection settings. const REDIS_URL = process.env.REDIS_URL ?? 'redis://127.0.0.1:6379'; const connection = new IORedis(REDIS_URL); // Create a new queue named 'email-queue' const emailQueue = new Queue('email-queue', { connection }); console.log('Queue created. Adding a job and setting up a worker...'); // Producer: Add a job to the queue emailQueue.add('sendEmail', { to: 'user@example.com', subject: 'Welcome to Our Service', body: 'Hello there! Thanks for signing up.', }, { attempts: 3, backoff: { type: 'exponential', delay: 1000 }, delay: 5000, // Delay job processing by 5 seconds removeOnComplete: true, // Automatically remove job from queue on completion }).then(job => { console.log(`Job '${job.id}' added to queue: sendEmail to ${job.data.to}`); }); // Consumer/Worker: Process jobs from the 'email-queue' emailQueue.process('sendEmail', async (job) => { const { to, subject, body } = job.data; console.log(`Processing job ${job.id}: Sending email to ${to} with subject '${subject}'`); // Simulate an asynchronous email sending operation await new Promise(resolve => setTimeout(resolve, Math.random() * 2000 + 500)); if (Math.random() < 0.1) { // 10% chance of failure console.error(`Job ${job.id} failed for ${to}. Will retry.`); throw new Error('Failed to send email (simulated error)'); } console.log(`Job ${job.id} completed: Email sent to ${to}.`); return { status: 'sent', recipient: to }; }); // Listen for global queue events emailQueue.on('completed', (job, result) => { console.log(`Global Event: Job ${job.id} completed with result:`, result); }); emailQueue.on('failed', (job, err) => { console.error(`Global Event: Job ${job.id} failed with error: ${err.message}`); }); console.log('Worker is listening for jobs...'); // Graceful shutdown process.on('SIGINT', async () => { console.log('Shutting down queues gracefully...'); await emailQueue.close(); await connection.quit(); console.log('Queues and Redis connection closed. Exiting.'); process.exit(0); });
Debug
Known issues
deprecatedThe Bull project is in maintenance mode; new features are not being added. For new projects or to leverage active development and modern features, consider migrating to BullMQ.
fix
For new applications, use BullMQ. For existing Bull applications, plan a migration to BullMQ for future-proofing and access to new features.
affects: >=4.0.0
breakingBull v4 introduced breaking changes, especially regarding Redis connection handling. It expects a direct `ioredis` client instance for the `connection` option instead of an object with `host`/`port` properties for older Redis clients.
fix
Ensure you are passing an instantiated `ioredis` client to the `connection` option of the `Queue` constructor: `new Queue('my-queue', { connection: new IORedis() });`.
affects: >=4.0.0
gotchaJobs can be considered 'stalled' and potentially double-processed if the worker's CPU usage is too high or the Redis connection is lost, preventing lock renewal.
fix
Optimize job processing logic to avoid blocking the Node.js event loop for extended periods. Consider using sandboxed processors (`queue.process('./path/to/processor.js')`) for CPU-intensive tasks. Monitor worker CPU usage and Redis connection health. Increase `lockDuration` if necessary, but be aware of the tradeoff.
affects: >=4.0.0
gotchaUpgraded `cron-parser` dependency to fix CVE-2023-22467, which addressed a potential ReDoS vulnerability when parsing specific cron expressions. Ensure you are on `v4.16.5` or later to mitigate this.
fix
Upgrade to Bull `v4.16.5` or a newer version to receive the fix for the `cron-parser` CVE.
affects: <4.16.5
gotchaA bug in the `msgpackr` dependency (prior to 1.1.2) could lead to an `ERR_BUFFER_OUT_OF_BOUNDS` error, particularly under heavy load or with specific data payloads.
fix
Upgrade to Bull `v4.16.4` or a newer version to get the fix by bumping `msgpackr` to version 1.1.2 or higher.
affects: <4.16.4
Errors
Common errors & fixes
Error: Redis connection to 127.0.0.1:6379 failed - connect ECONNREFUSED
The Bull queue could not establish a connection to the Redis server. This often means Redis is not running, is running on a different port, or a firewall is blocking the connection.
fix
Verify that your Redis server is running and accessible from the application's host and port (default is `localhost:6379`). Check firewall rules. Ensure the `redis` or `connection` options in the Bull `Queue` constructor correctly point to your Redis instance.
Missing lock for job 1234. moveToFinished.
A job being processed by a worker lost its lock before completion, potentially leading to double processing. Common causes include high CPU usage preventing lock renewal, lost Redis connection, or forceful job removal.
fix
Optimize job processing code to be less CPU-intensive, use sandboxed processors, or increase `lockDuration`. Check network stability to Redis. Ensure Redis `maxmemory-policy` is set to `noeviction` to prevent Redis from prematurely deleting keys.
ERR Error running script ... Lua redis() command arguments must be strings or integers.
This error typically occurs when environment variables (or other parameters) used for queue names, job data, or other Redis commands are `undefined`, empty strings, or non-string/non-integer values, causing Bull's internal Lua scripts to fail.
fix
Validate all environment variables and dynamic parameters before passing them to Bull constructors or methods. Ensure they are always defined and of the correct `string` or `number` type, using default values or throwing explicit errors if they are missing.
Upgrade
Version history
0.4.1latest on npm
Audit
Dependencies
RedisrequiredRequired as the persistent storage backend for all queues and job data. Bull leverages Redis's atomic operations for reliability. Requires Redis version >= 2.8.18.
Agent activity
29 hits · last 30 days
node
26
OpenAI (training)
1
Resources