BullMQ in production: the retry, stalled-job and Redis connection mistakes that bite

BullMQ is a simple library to work with queues, workers and Redis connections. However, several common mistakes can cause issues under load, during deploys or when Redis restarts. This article covers these mistakes, explains why they happen, and provides solutions. All information is based on the BullMQ source (v6.4.2) and the official going-to-production guide. A lint configuration is provided at the end to catch four of these mistakes before shipping.

1. Sharing one ioredis connection with maxRetriesPerRequest set to its default value. This is the most frequent mistake. If your project uses BullMQ 6, you need to install both bullmq and ioredis. Create a separate ioredis connection for each Worker, not sharing a single connection:

import { Queue, Worker } from 'bullmq';

import IORedis from 'ioredis';

const connection = new IORedis(process.env.REDIS_URL);

const queue = new Queue('emails', { connection });

const worker = new Worker('emails', processEmail, { connection });

2. Not attaching an error listener to both Worker and Queue. Workers and Queues are Node.js events. If an error occurs and no listener is present, Node throws an error, causing the process to crash. Always listen for errors on both the Worker and Queue:

worker.on('error', (err) => logger.error({ err }, 'worker error'));

queue.on('error', (err) => logger.error({ err }, 'queue error'));

3. Assuming jobs automatically retry when an error occurs. By default, a job runs once and fails immediately if an error occurs. To enable retries, set the attempts option with a value greater than 1 and configure the backoff settings. This will ensure the job is retried according to the specified backoff strategy. If a job is unrecoverable, throw BullMQ's UnrecoverableError to stop retries:

const queue = new Queue('emails', {

connection,

defaultJobOptions: {

attempts: 5,

backoff: { type: 'exponential', delay: 1000 },

removeOnComplete: { age: 24 * 3600, count: 1000 },

removeOnFail: { age: 7 * 24 * 3600, count: 5000 },

},

});

4. Not using custom jobIds to avoid duplicates. When a webhook is delivered multiple times, adding the job with the same ID will result in duplicate jobs. To prevent this, use a custom jobId that uniquely identifies each job, such as including a unique identifier in the jobId.