{"id":10383,"library":"bull","title":"Bull Job Queue","description":"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.","status":"maintenance","version":"4.16.5","language":"javascript","source_language":"en","source_url":"git://github.com/OptimalBits/bull","tags":["javascript","job","queue","task","parallel","typescript"],"install":[{"cmd":"npm install bull","lang":"bash","label":"npm"},{"cmd":"yarn add bull","lang":"bash","label":"yarn"},{"cmd":"pnpm add bull","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required 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.","package":"Redis","optional":false}],"imports":[{"note":"While `require` works for CommonJS, modern Node.js applications and TypeScript projects should use ES module `import` syntax.","wrong":"const Queue = require('bull');","symbol":"Queue","correct":"import Queue from 'bull';"},{"note":"`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.","wrong":"import Job from 'bull';","symbol":"Job","correct":"import { Job } from 'bull';"},{"note":"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.","symbol":"QueueEvents","correct":"import { QueueEvents } from 'bull';"}],"quickstart":{"code":"import Queue from 'bull';\nimport IORedis from 'ioredis';\n\n// Ensure a Redis server is running at localhost:6379 or configure as needed.\n// For production, always use robust Redis connection settings.\nconst REDIS_URL = process.env.REDIS_URL ?? 'redis://127.0.0.1:6379';\nconst connection = new IORedis(REDIS_URL);\n\n// Create a new queue named 'email-queue'\nconst emailQueue = new Queue('email-queue', { connection });\n\nconsole.log('Queue created. Adding a job and setting up a worker...');\n\n// Producer: Add a job to the queue\nemailQueue.add('sendEmail', {\n  to: 'user@example.com',\n  subject: 'Welcome to Our Service',\n  body: 'Hello there! Thanks for signing up.',\n}, {\n  attempts: 3,\n  backoff: { type: 'exponential', delay: 1000 },\n  delay: 5000, // Delay job processing by 5 seconds\n  removeOnComplete: true, // Automatically remove job from queue on completion\n}).then(job => {\n  console.log(`Job '${job.id}' added to queue: sendEmail to ${job.data.to}`);\n});\n\n// Consumer/Worker: Process jobs from the 'email-queue'\nemailQueue.process('sendEmail', async (job) => {\n  const { to, subject, body } = job.data;\n  console.log(`Processing job ${job.id}: Sending email to ${to} with subject '${subject}'`);\n\n  // Simulate an asynchronous email sending operation\n  await new Promise(resolve => setTimeout(resolve, Math.random() * 2000 + 500));\n\n  if (Math.random() < 0.1) { // 10% chance of failure\n    console.error(`Job ${job.id} failed for ${to}. Will retry.`);\n    throw new Error('Failed to send email (simulated error)');\n  }\n\n  console.log(`Job ${job.id} completed: Email sent to ${to}.`);\n  return { status: 'sent', recipient: to };\n});\n\n// Listen for global queue events\nemailQueue.on('completed', (job, result) => {\n  console.log(`Global Event: Job ${job.id} completed with result:`, result);\n});\n\nemailQueue.on('failed', (job, err) => {\n  console.error(`Global Event: Job ${job.id} failed with error: ${err.message}`);\n});\n\nconsole.log('Worker is listening for jobs...');\n\n// Graceful shutdown\nprocess.on('SIGINT', async () => {\n  console.log('Shutting down queues gracefully...');\n  await emailQueue.close();\n  await connection.quit();\n  console.log('Queues and Redis connection closed. Exiting.');\n  process.exit(0);\n});","lang":"typescript","description":"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."},"warnings":[{"fix":"For new applications, use BullMQ. For existing Bull applications, plan a migration to BullMQ for future-proofing and access to new features.","message":"The 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.","severity":"deprecated","affected_versions":">=4.0.0"},{"fix":"Ensure you are passing an instantiated `ioredis` client to the `connection` option of the `Queue` constructor: `new Queue('my-queue', { connection: new IORedis() });`.","message":"Bull 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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"Jobs 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.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"Upgrade to Bull `v4.16.5` or a newer version to receive the fix for the `cron-parser` CVE.","message":"Upgraded `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.","severity":"gotcha","affected_versions":"<4.16.5"},{"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.","message":"A 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.","severity":"gotcha","affected_versions":"<4.16.4"}],"env_vars":null,"search_vec":"'4.16.5':40 'activ':117,136 'atom':34 'back':12 'background':20 'battl':8 'battle-test':7 'buffer':89 'bug':55 'bull':1,4,91 'bullmq':126 'cadenc':68 'ceas':65 'consid':125 'cpu':103 'critic':76 'cron':82 'cron-pars':81 'current':36 'cves':79 'defer':22 'design':17,100 'develop':63,119 'distinguish':92 'distribut':25 'driven':71 'e.g':80,87 'emphasi':30 'encourag':123 'error':86 'featur':62,118 'fix':56 'free':99 'handl':19 'irregular':70 'issu':77,90 'javascript':139 'job':2,13,110,140 'larg':64 'least':108 'like':78 'maintain':137 'mainten':49 'manag':14 'mean':51 'minim':102 'mode':50 'modern':130 'msgpackr':88 'necessari':73 'new':61,114 'node.js':16 'parallel':143 'parser':83 'patch':74 'poll':98 'polling-fre':97 'primarili':53 'process':23,111 'project':46,115 'queue':3,141 'receiv':54 'recent':43 'redi':11 'redis-back':10 'releas':67 'reliabl':106 'rewrit':131 'robust':96 'runtim':85 'secur':58 'semant':112 'stabil':32 'stabl':37 'strong':29,122 'successor':138 'task':21,142 'test':9 'typescript':133,144 'updat':44,59 'usag':104 'user':120 'version':38 'workload':26","created_at":"2026-04-18T08:58:31.105942+00:00","updated_at":"2026-04-19T05:46:53.307670+00:00","problems":[{"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.","cause":"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.","error":"Error: Redis connection to 127.0.0.1:6379 failed - connect ECONNREFUSED"},{"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.","cause":"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.","error":"Missing lock for job 1234. moveToFinished."},{"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.","cause":"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.","error":"ERR Error running script ... Lua redis() command arguments must be strings or integers."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.4.1","cli_name":"","cli_version":null,"type":"library","homepage":"https://optimalbits.github.io/bull","github":"https://github.com/OptimalBits/bull","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/bull","openapi_spec":null,"status_page":null,"smithery":null,"categories":["workflow","database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}