How does it work? Producers, workers and Redis in a NestJS BullMQ queue

BullMQ is a Node.js job queue library that stores jobs, their state and their schedules in Redis. A producer adds a job to a named queue. A worker pulls jobs off that queue, runs them, and records whether each one completed or failed. Redis holds everything in between, so jobs survive a restart of the producer and can be consumed by any number of worker processes.

In NestJS, the @nestjs/bullmq package wires this into the module system in three steps:

  • Register the queue. BullModule.forRoot sets the Redis connection, and BullModule.registerQueue declares a named queue inside a feature module.
  • Produce jobs. A service injects the queue with @InjectQueue('name') and calls queue.add() with a job name and payload. The HTTP handler returns as soon as Redis accepts the job.
  • Consume jobs. A class decorated with @Processor('name') extends WorkerHost and implements process(job). That class is the worker.

The worker is a separate consumer from the producer. It can run inside the API process, but a dedicated worker deployment is usually the better choice. Slow jobs then cannot compete with request handlers for CPU or the event loop, and you can scale workers to match job volume rather than HTTP traffic.

This setup is aimed at backend and platform engineers whose jobs call rate-limited APIs, write to shared databases, or cause side effects such as charging a card or sending an email. For those jobs, retries, concurrency and rate limiting are not three separate settings. They form one design decision, and two things drive it: how much load the downstream system can absorb, and whether the job is safe to run twice.

import { Injectable, Module } from '@nestjs/common';
import { BullModule, InjectQueue, Processor, WorkerHost } from '@nestjs/bullmq';
import { Job, Queue } from 'bullmq';

// Producer: the HTTP path only enqueues and returns once Redis accepts the job.
@Injectable()
export class EmailService {
  constructor(@InjectQueue('email') private readonly emailQueue: Queue) {}

  async sendWelcome(userId: string) {
    await this.emailQueue.add('welcome', { userId });
  }
}

// Consumer: this class is the worker. Run it in a dedicated deployment
// so slow jobs never compete with request handlers for the event loop.
@Processor('email')
export class EmailProcessor extends WorkerHost {
  async process(job: Job<{ userId: string }>): Promise<void> {
    // Side effect: this may run more than once, so it must be safe to repeat.
    console.log(`sending ${job.name} email to user ${job.data.userId}`);
  }
}

@Module({
  imports: [
    // Shared Redis connection for all queues in the app.
    BullModule.forRoot({ connection: { host: 'localhost', port: 6379 } }),
    // Declares the named queue that producer and worker both refer to.
    BullModule.registerQueue({ name: 'email' }),
  ],
  providers: [EmailService, EmailProcessor],
})
export class EmailModule {}

A minimal NestJS module that registers an 'email' queue in BullMQ, enqueues jobs from an injected service, and consumes them in a WorkerHost processor.

Who should use NestJS BullMQ?

NestJS with BullMQ is a good fit for these groups:

  • Backend engineers on NestJS services who need to move slow or unreliable work out of the request path. Typical examples are sending email, calling partner APIs, delivering webhooks and generating reports. The API responds quickly, and the worker retries the work without the user waiting on it.
  • Teams that already run Redis in production and are willing to operate it as durable infrastructure, with persistence, memory alerts and failover, rather than as a disposable cache.
  • Platform engineers who own a shared downstream quota, such as a third-party API key used by several services. A queue-wide limiter plus per-worker concurrency gives them one place to control how hard the fleet hits that dependency.
  • Engineers whose jobs are mostly I/O-bound and can be made idempotent. BullMQ's at-least-once delivery, retries and stall recovery work best when running a job twice is harmless.

It is a weaker fit for teams that cannot operate Redis reliably, for workloads that need strict global ordering or fair per-tenant limits out of the box, and for long-running or CPU-heavy jobs. Those cases are covered in the last section.

Why must jobs be idempotent before you enable job retries?

BullMQ delivers jobs at least once, not exactly once. A worker holds a lock on each active job and must renew it. If the worker's event loop is blocked long enough, or the process dies, the lock expires. The job is then treated as stalled and returned to the queue. The same thing happens when a handler charges a card or sends an email and then crashes before the completion is recorded. The side effect has already happened, and the next attempt will do it again. Retries make this more likely, because every attempt is a fresh execution of the whole handler.

Deduplicate at both ends

At enqueue time, give jobs a stable custom job ID derived from the business event, such as an order ID plus an action name. BullMQ will not add a second job with an ID that already exists. This protects you from producers that publish twice. It only holds while the original job is still stored, so your completed-job retention settings determine how long the deduplication window lasts.

Inside the handler, protect each side effect with an idempotency key or an upsert-style write. Many payment APIs accept an idempotency key. For your own database, use a unique constraint and an insert-if-absent or upsert.

This takes design effort, and sometimes extra storage for keys. That cost is small next to refunding double charges or apologising for duplicate emails.

Ordering is not guaranteed

With concurrency above one, or with more than one worker, jobs can finish in a different order than they were added. If you need strict ordering, you have two choices. You can give up parallelism and run a single worker at concurrency one. Or you can partition the work so that each ordered stream is processed serially.

import { Injectable } from '@nestjs/common';
import { InjectQueue, Processor, WorkerHost } from '@nestjs/bullmq';
import { Job, Queue } from 'bullmq';
import { Pool } from 'pg';

// Placeholder for an email client that accepts an idempotency key.
export abstract class Mailer { abstract sendReceipt(orderId: string, idempotencyKey: string): Promise<void>; }

@Injectable()
export class ReceiptProducer {
  constructor(@InjectQueue('receipts') private readonly queue: Queue) {}

  async enqueue(orderId: string) {
    // Stable ID from the business event: a duplicate add is ignored while this job is still stored.
    await this.queue.add('send-receipt', { orderId }, {
      jobId: `order-${orderId}-send-receipt`,
      attempts: 5,
      backoff: { type: 'exponential', delay: 1000 },
      removeOnComplete: { age: 24 * 3600 }, // retention = deduplication window (24h)
    });
  }
}

@Processor('receipts', { concurrency: 5 }) // concurrency > 1: completion order is not guaranteed
export class ReceiptProcessor extends WorkerHost {
  constructor(private readonly db: Pool, private readonly mailer: Mailer) { super(); }

  async process(job: Job<{ orderId: string }>) {
    const key = `receipt-${job.data.orderId}`;
    // Insert-if-absent against a UNIQUE key column; safe to run on every attempt.
    await this.db.query(
      `INSERT INTO sent_receipts (key, status) VALUES ($1, 'pending') ON CONFLICT (key) DO NOTHING`, [key]);
    const { rows } = await this.db.query(`SELECT status FROM sent_receipts WHERE key = $1`, [key]);
    if (rows[0].status === 'sent') return; // an earlier attempt already finished the side effect
    // If we crashed after sending last time, the provider dedupes on the same key.
    await this.mailer.sendReceipt(job.data.orderId, key);
    await this.db.query(`UPDATE sent_receipts SET status = 'sent' WHERE key = $1`, [key]);
  }
}

A NestJS producer that deduplicates at enqueue time with a stable custom jobId, paired with a processor that guards its email side effect with a unique-key insert-if-absent and an idempotency key, so retries and stalled-job reruns do not send the receipt twice.

How should you configure job retries and backoff in BullMQ?

Retries are configured per job through two options: attempts, the total number of tries including the first, and backoff, which sets the wait between tries. You can set them on each add() call or as default job options when registering the queue in your NestJS module. Defaults keep policy in one place. Per-job overrides are useful when one job type calls a more fragile dependency than the others.

Backoff type Delay between attempts Load on a failing dependency Time to final failure
fixed Same delay each time Constant, arrives in waves Short and predictable
exponential Base delay doubles after each failure Falls off quickly Long, and grows fast with attempts

A retry only helps when the next attempt can succeed. Timeouts, connection resets, and 429 or 503 responses from a downstream API are transient, so they are worth retrying. A payload that fails validation or references a deleted record will fail every time, and each retry occupies a worker slot for nothing. For these cases, throw BullMQ's UnrecoverableError. The job moves straight to failed, and any remaining attempts are skipped.

The main risk is in tuning. Many attempts with a short fixed delay turn a brief downstream outage into a retry storm. Every queued job hits the recovering service on the same cadence, which can keep it down. Exponential backoff with a capped attempts count spreads that load out, but it has costs. Jobs stay in the delayed set longer, recovery after the outage is slower, and the backlog grows while you wait.

import { Module } from '@nestjs/common';
import { BullModule, Processor, WorkerHost } from '@nestjs/bullmq';
import { Job, UnrecoverableError } from 'bullmq';

// Queue-wide default: 5 tries total, waits of 1s, 2s, 4s, 8s between them.
// Exponential backoff spreads retries out so a recovering API is not hammered.
export const webhookQueue = BullModule.registerQueue({
  name: 'webhooks',
  defaultJobOptions: {
    attempts: 5,
    backoff: { type: 'exponential', delay: 1000 },
  },
});
// Per-job override for a fragile dependency, e.g.:
// await queue.add('send', data, { attempts: 3, backoff: { type: 'fixed', delay: 5000 } });

@Processor('webhooks')
export class WebhookProcessor extends WorkerHost {
  async process(job: Job<{ url?: string; payload: unknown }>) {
    // Permanent failure: bad input fails every time, so skip remaining attempts.
    if (!job.data.url) {
      throw new UnrecoverableError('Missing url; not retrying');
    }

    const res = await fetch(job.data.url, {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify(job.data.payload),
      signal: AbortSignal.timeout(10_000), // timeouts throw and are retried
    });

    // Transient: a plain Error lets BullMQ schedule the next attempt with backoff.
    if (res.status === 429 || res.status === 503) {
      throw new Error(`Downstream unavailable (${res.status}); will retry`);
    }
    // Other 4xx responses mean the request itself is wrong, so fail fast.
    if (res.status >= 400 && res.status < 500) {
      throw new UnrecoverableError(`Rejected with ${res.status}`);
    }
  }
}

@Module({ imports: [webhookQueue], providers: [WebhookProcessor] })
export class WebhooksModule {}

A NestJS BullMQ queue with exponential backoff as the default job option and a per-job fixed-backoff override, plus a processor that rethrows transient errors (timeouts, 429, 503) so they are retried and throws UnrecoverableError on permanent failures so they skip the remaining attempts.

What is the difference between BullMQ concurrency and rate limiting?

Concurrency and rate limiting control different things. concurrency is a per-worker setting: a worker with concurrency: 10 holds up to ten jobs in flight inside one Node process. Running that worker in four pods gives roughly 40 concurrent jobs, because effective parallelism is about concurrency multiplied by worker instances. Scaling pods therefore changes your load on downstream systems even when no config file changes.

Concurrency within one process only helps I/O-bound jobs. While one job awaits an HTTP call or a database query, the event loop runs another. CPU-bound work such as image resizing or PDF rendering blocks the event loop, so a higher number adds latency without adding throughput. For CPU-heavy jobs, use sandboxed processors (a processor file run in a child process or worker thread) or a separate deployment.

The worker-level limiter (max jobs per duration milliseconds) keeps its state in Redis, so the limit applies across every worker on the queue, not per pod.

Setting Caps Scope Grows with pod count?
concurrency Jobs in flight One worker instance Yes
limiter Job starts per time window Whole queue (Redis) No

When a downstream API returns 429, do not throw an ordinary error, because that consumes one of the job's retry attempts. Instead, call worker.rateLimit() with the Retry-After duration and throw the rate-limit error, or move the job to delayed.

High concurrency also widens the blast radius. Each pod opens more connections and holds more memory, and a burst exhausts shared quota faster.

import { Processor, WorkerHost } from '@nestjs/bullmq';
import { Job, Worker } from 'bullmq';

// Base URL of the partner API, supplied via configuration.
const PARTNER_API_BASE = process.env.PARTNER_API_BASE ?? '';

// concurrency: per worker instance, so 4 pods => ~40 jobs in flight.
// limiter: state lives in Redis, so 50 starts/sec is shared by ALL pods.
@Processor('partner-sync', {
  concurrency: 10,
  limiter: { max: 50, duration: 1000 },
})
export class PartnerSyncProcessor extends WorkerHost {
  async process(job: Job<{ accountId: string }>): Promise<void> {
    // I/O-bound: while this awaits, the event loop runs other jobs.
    const res = await fetch(
      `${PARTNER_API_BASE}/accounts/${job.data.accountId}/sync`,
      { method: 'POST' },
    );

    if (res.status === 429) {
      // Respect the server's backoff hint; fall back to 30s if missing.
      const retryAfterSec = Number(res.headers.get('retry-after')) || 30;

      // Pause the whole queue in Redis, not just this pod.
      await this.worker.rateLimit(retryAfterSec * 1000);

      // Special error: the job goes back to wait without
      // consuming one of its retry attempts.
      throw Worker.RateLimitError();
    }

    if (!res.ok) {
      // Genuine failure: counts against job.opts.attempts.
      throw new Error(`Partner sync failed with ${res.status}`);
    }
  }
}

A NestJS BullMQ processor that combines per-worker concurrency with a Redis-backed queue limiter and handles a downstream 429 by calling worker.rateLimit() and throwing Worker.RateLimitError(), so the job is not counted as a failed attempt.

How do you derive concurrency and limiter settings from a downstream API limit?

Illustrative estimate, with assumed inputs: the downstream API allows N = 50 requests/second, you run K = 4 worker pods, each job makes exactly one API call, and an average job takes 400 ms.

Limiter. BullMQ enforces the limiter through Redis for the whole queue, not per worker. Do not divide it by K. Do not set it to 50 either. Clock skew, other clients that share the same API key, and bursts at the window boundary all push you over. Target about 80% of the limit: max: 40 per duration: 1000.

Concurrency. Little's law gives the number of jobs in flight: throughput × duration = 40 × 0.4 s = 16 jobs across the fleet. That is 4 per pod. Set it to 5 so that slow responses don't leave you under the limiter. The limiter caps throughput, so extra concurrency only adds idle slots.

Retries. Each retry is another attempt, and it counts against the same 40/s. At an assumed 10% failure rate, attempts run at about 1.1× first attempts, so new work gets roughly 36/s. During a partial outage the failure rate climbs, and retries can take most of the budget. That is the reason for the 20% headroom.

Setting Value Derived from
Limiter 40 per 1000 ms 80% of N, queue-wide
Concurrency 5 per pod 40 × 0.4 s ÷ 4 pods, plus slack
Effective first-attempt rate ~36/s 40 ÷ 1.1 retry multiplier

If you change one of these values, recompute the other two. Doing this arithmetic before deploying is cheaper than diagnosing 429 storms from incident dashboards.

How do stalled jobs, failure visibility and graceful shutdown work in production?

A job stalls when its worker stops renewing the job's lock in Redis before the lock expires. BullMQ then assumes the worker died and moves the job back to waiting, so another worker runs it again. A dead worker is one cause. Another is a handler that blocks the event loop with synchronous work such as parsing a large payload or CPU-heavy hashing. Lock renewal runs on that same loop, so it cannot fire, and you get a duplicate run while the first one is still executing. Split CPU work into chunks that yield, or move it to worker threads, and keep each uninterrupted stretch well under the lock duration. Raising lockDuration reduces false stalls, but it also delays detection of workers that really have crashed.

Subscribe to completed, failed and stalled events. On every failure, log the job ID, attemptsMade and the error, so retries and stalls can be correlated in your log pipeline.

Set removeOnComplete and removeOnFail with a count or age limit. Without them, finished jobs accumulate in Redis indefinitely. Keep failed jobs longer than completed ones. The failed set then works as a dead-letter queue: inspect the jobs, fix the cause, and replay them through a deliberate script or admin endpoint rather than by hand.

Call app.enableShutdownHooks() so that SIGTERM closes workers. Closing stops new pickups and waits for in-flight jobs to finish. Your orchestrator's termination grace period must exceed your longest expected job, or the process is killed mid-job and the job stalls.

Treat Redis as critical infrastructure:

  • Enable persistence.
  • Set maxmemory-policy noeviction, because any eviction policy can silently delete queue keys.
  • Alert on memory growth.
  • Plan for failover. Replication is asynchronous, so a promoted replica can lose recent writes, and handlers must tolerate jobs that reappear.

How can NestJS BullMQ save engineering time?

Most of the saving comes from code and incidents your team does not have to deal with:

  • No hand-rolled retry plumbing. attempts, backoff, UnrecoverableError and delayed jobs replace the retry loops, sleep timers and "retry later" tables that teams otherwise write and debug for each integration. The retry policy becomes queue configuration that you can review in one place.
  • One shared throttle instead of per-service coordination. The Redis-backed limiter and worker.rateLimit() enforce a downstream quota across every pod. You don't need to build a distributed rate limiter, and adding pods does not silently break the quota.
  • Framework-native wiring. @InjectQueue and @Processor follow the same dependency-injection patterns as the rest of a NestJS codebase. Producers and workers can be unit-tested by injecting a mock queue or calling process() directly, and engineers new to the service do not have to learn a separate worker framework.
  • Faster failure triage. Failed jobs keep their payload, attemptsMade and error in Redis. Combined with event logging, this means an engineer can see what failed and why, fix the cause, and replay the job deliberately. The alternative is reconstructing lost work from application logs.
  • Fewer incidents from capacity mistakes. Deriving limiter and concurrency from the downstream limit before deploying, as shown above, turns a class of 429 storms and retry cascades into a short calculation done during design review.
  • Faster API responses without extra infrastructure. If Redis is already in the stack, moving slow work out of request handlers needs no new cluster, broker or workflow service to provision and learn.

The time saved depends on idempotent handlers and a properly operated Redis. Without those, effort shifts from writing retry code to investigating duplicate side effects and lost jobs.

When should you avoid BullMQ, and what are the alternatives?

BullMQ fits well when your services already run on Node, Redis is already part of your operated stack, and the background work is I/O-bound: calling APIs, sending email, generating webhooks. It is especially convenient when one downstream limit applies globally, because a per-queue limiter maps directly onto that constraint.

Avoid it, or plan for extra work, in these situations:

  • Per-tenant or per-key rate limits. The built-in limiter applies to the whole queue. Fair per-tenant throttling needs separate queues, grouping, or your own token logic.
  • Strict ordering. Retries, concurrency above one, and backoff delays all reorder jobs. A single worker with concurrency one is the only straightforward way to get FIFO, and it gives up throughput.
  • Redis treated as a cache. If your team will not configure persistence, memory alerts and failover, queued jobs can be lost without any error.
  • Long or CPU-heavy work. Hours-long jobs make lock renewal and stall detection fragile. CPU-bound handlers block the event loop and need sandboxed processes or a different runtime.
Approach Operational overhead Development cost Delivery guarantee
Inline in the request None Lowest None beyond the request; failures surface to the caller
Database job table Low; reuses existing DB Moderate; you build polling and locking Transactional enqueue with business data
Message broker High; new cluster to run Moderate At-least-once, with stronger durability and ordering options
Workflow engine Highest Higher up front Durable multi-step state, timers and resumable retries

A database job table is often the underrated option. It lets you enqueue a job in the same transaction as the write that caused it, which removes a whole class of "row saved, job lost" bugs.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to nestjs bullmq, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Changing a shared variable is one edit and one review instead of editing every service's .env by hand.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.