bullmq 5.x

Complete instructions

BullMQ 5

Inspect the installed versions, queues, prefixes, Redis topology and worker lifecycle first. This line targets BullMQ 5.81.4 with ioredis 5.11.1. Preserve project concurrency, retention and retry policy.

Produce and consume

Use matching queue names and prefixes for Queue, Worker and QueueEvents. Request producers need bounded failure; worker connections need maxRetriesPerRequest: null. QueueEvents needs its own blocking connection; do not share a Pub/Sub connection.

import type Redis from "ioredis";
import { Queue, Worker } from "bullmq";

export function createWorkflow(
  producer: Redis,
  workerConnection: Redis,
  prefix: string,
) {
  const queue = new Queue("jobs", { connection: producer, prefix });
  const worker = new Worker(
    "jobs",
    async (job) => {
      if (typeof job.data.value !== "number") throw new Error("Invalid value");
      return job.data.value * 2;
    },
    { connection: workerConnection, prefix, concurrency: 1 },
  );
  return { queue, worker };
}

The caller must create workerConnection with maxRetriesPerRequest: null, register operational error listeners and own shutdown. Add jobs with queue.add(name, data, { attempts, backoff }); TypeScript job types do not validate incoming JSON.

Verify state

Wait for worker and QueueEvents readiness. In bounded integration tests, use job.waitUntilFinished(queueEvents, timeout) and check stored state. A return value and completed state differ from a rejected waiter and failed state.

Use a transient failure that succeeds on a configured later attempt and a permanent failure that exhausts attempts. Inspect attemptsMade on a refreshed job, not a stale object. An error event is not a completed job.

Retries and stalled recovery can execute work more than once. Make side effects idempotent. jobId deduplicates additions only while that job exists; removing a completed job permits reuse. Job IDs do not establish exactly-once delivery.

Own shutdown

await worker.close() stops taking jobs and waits for active work. It has no overall deadline; the host must bound shutdown and choose a forced-stop policy. Close workers, queue event consumers, queues and finally caller-owned Redis clients. A queue does not own an independently supplied ioredis client.

Tests need a unique prefix and cleanup of only their queue after workers stop. Never obliterate an application queue as fixture setup. Review Redis noeviction with the service owner instead of modifying shared configuration from a helper.

The fixture targets one worker, concurrency 1, completion, retry, permanent failure, a network interruption and graceful close during active work. It does not establish production stalled-job recovery, multiple-worker coordination, repeatable scheduling, Cluster/Sentinel or BullMQ Pro behavior.

Primary sources

• Connections
• Graceful shutdown
• Production guidance
• Upstream