What is NestJS BullMQ and how does a job queue in NestJS work?

BullMQ is a Node.js job queue that stores jobs, their state and their locks in Redis. The @nestjs/bullmq package wraps it in Nest's module and dependency-injection system. Register the Redis connection once with BullModule.forRoot({ connection }) and declare each queue with BullModule.registerQueue({ name: 'emails' }). A service then receives the queue through @InjectQueue('emails') and calls queue.add('welcome', payload), which writes the job to Redis and returns immediately. On the consuming side, a class decorated with @Processor('emails') extends WorkerHost and implements async process(job). Nest creates the underlying BullMQ Worker for you.

This pattern is for backend teams who need to move slow or unreliable work out of the request path. Typical uses are sending email, calling third-party APIs, generating files and syncing to other systems. The queue gives you retries against flaky dependencies and absorbs traffic spikes: the API accepts work at peak rate while workers drain it at a rate downstream systems can handle.

 [API pods] --add--> [ Redis ] <--fetch/lock-- [worker 1] --> payment API
  (producers)                  <--fetch/lock-- [worker 2] --> SMTP
                               <--fetch/lock-- [worker N] --> S3

You can run producers and the @Processor in the same process. That means one deployable and one config, which is fine early on. Splitting them into separate deployables, with the same codebase and different entry modules, lets you scale workers on queue depth instead of HTTP load. It also lets you redeploy or drain workers without touching the API. The cost is a second service to build, monitor and keep schema-compatible with the jobs the API enqueues.

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

// Producer side: the API enqueues and returns without waiting for the work.
@Injectable()
export class SignupService {
  constructor(@InjectQueue('emails') private readonly emails: Queue) {}

  async onUserCreated(userId: string, email: string) {
    // Writes the job to Redis; a worker picks it up later.
    await this.emails.add('welcome', { userId, email });
  }
}

// Consumer side: Nest creates the BullMQ Worker for this class.
@Processor('emails')
export class EmailProcessor extends WorkerHost {
  async process(job: Job<{ userId: string; email: string }>): Promise<void> {
    if (job.name === 'welcome') {
      // Slow or flaky I/O (SMTP, third-party API) goes here.
      // Throwing marks the job failed so retry settings can apply.
    }
  }
}

@Module({
  imports: [
    // One shared Redis connection for every queue in this app.
    BullModule.forRoot({ connection: { host: 'redis.internal', port: 6379 } }),
    BullModule.registerQueue({ name: 'emails' }),
  ],
  // In a split deployment, the API module lists only SignupService
  // and a separate worker entry module lists only EmailProcessor.
  providers: [SignupService, EmailProcessor],
})
export class EmailsModule {}

A single Nest module that registers the Redis connection and an 'emails' queue, enqueues a job from a service via the injected Queue, and consumes it in a @Processor class extending WorkerHost.

How do BullMQ retries work, and when is a job safe to retry?

Retries in BullMQ are configured per job with attempts and backoff. An attempt fails when the processor throws or its returned promise rejects. BullMQ then reschedules the job with a delay until attempts is used up. A fixed backoff waits the same delay every time. An exponential backoff doubles the delay after each failure, starting from the configured base.

Backoff Delay pattern Good for Risk
fixed Same delay each attempt Short blips, rate-limited APIs with known reset windows Keeps hammering a dependency that is fully down
exponential Base delay doubling per attempt Outages of unknown length Slower recovery; jobs queued during the outage can retry together when the dependency returns

Not every error should be retried. Validation failures and downstream 4xx responses will fail the same way every time. For these, throw UnrecoverableError from bullmq, which sends the job straight to failed without using the remaining attempts.

The more important point is that BullMQ delivers jobs at least once. A worker can finish the side effect and then crash before it acknowledges the job, so the job runs again. Retries are only safe when the job is idempotent:

  • Deterministic jobId (for example invoice:${orderId}). BullMQ ignores an add whose ID matches an existing job, which stops duplicate enqueues.
  • Idempotency keys passed to downstream APIs that support them, so a repeated charge or email request is recognised and dropped.
  • A processed marker or unique constraint written in the same database transaction as the side effect. A replay then either sees the marker or fails on the constraint, instead of writing twice.
import { InjectQueue, Processor, WorkerHost } from '@nestjs/bullmq';
import { Injectable } from '@nestjs/common';
import { Job, Queue, UnrecoverableError } from 'bullmq';
// Db and PaymentsClient are app-specific placeholders (SQL client, HTTP client).

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

  enqueue(orderId: string) {
    return this.queue.add('charge', { orderId }, {
      jobId: `invoice-${orderId}`, // same order -> same id -> duplicate add is ignored
      attempts: 5,
      backoff: { type: 'exponential', delay: 1000 }, // retries after ~1s, 2s, 4s, 8s
    });
  }
}

@Processor('invoices')
export class InvoiceProcessor extends WorkerHost {
  constructor(private readonly db: Db, private readonly payments: PaymentsClient) { super(); }

  async process(job: Job<{ orderId: string }>) {
    const { orderId } = job.data;
    // Same key on every attempt, so the provider drops a repeated charge.
    const res = await this.payments.charge(orderId, { idempotencyKey: `charge-${orderId}` });
    if (res.status >= 400 && res.status < 500) {
      throw new UnrecoverableError(`charge rejected: ${res.status}`); // permanent: skip remaining attempts
    }
    if (res.status >= 500) throw new Error(`payments unavailable: ${res.status}`); // transient: retry with backoff

    await this.db.transaction(async (tx) => {
      // UNIQUE(order_id) makes a replay after a crash a no-op instead of a second invoice.
      await tx.query(
        'INSERT INTO invoices (order_id, charge_id) VALUES ($1, $2) ON CONFLICT (order_id) DO NOTHING',
        [orderId, res.chargeId],
      );
    });
  }
}

A NestJS producer and processor that combine a deterministic jobId, exponential backoff, UnrecoverableError for 4xx responses, a downstream idempotency key and a unique-constraint insert so an at-least-once retry cannot double-charge or double-write.

What happens when a job exhausts its retries?

Once attemptsMade reaches the job's attempts limit, BullMQ moves the job into the queue's failed set. It keeps its data, the last error message and stack trace, and stays there until something removes it. You can list failed jobs with queue.getFailed(). After fixing the root cause, such as a bad deploy or a downstream outage, you can re-queue an individual job with job.retry(). A manual retry runs the job again from the start, so it depends on the idempotency guarantees described above.

By default, completed and failed jobs are never removed, and Redis memory grows without bound. Set removeOnComplete and removeOnFail as default job options. Each takes a count (keep the most recent N) or an age in seconds (keep jobs newer than this). A typical setup keeps completed jobs only briefly and failed jobs much longer, because failures are what you investigate.

Failed jobs can stay in the failed set or be copied somewhere you control:

Approach Forensics Memory control Effort
Keep in failed set Full job data, until trimmed removeOnFail limits None
Own dead-letter queue Custom retention, can be replayed in bulk Separate limits per queue Final-failure handler you write and test

To build a dead-letter queue, listen for the worker's failed event. In NestJS, use @OnWorkerEvent('failed'). When the attempts are exhausted, enqueue a copy of the job to the dead-letter queue.

Check Redis's maxmemory-policy as well. With any evicting policy, such as allkeys-lru, Redis can delete queue keys under memory pressure, and jobs disappear without an error. Use noeviction, and configure persistence (AOF or RDB) to match how much queue state you can afford to lose.

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

@Processor('emails')
export class EmailProcessor extends WorkerHost {
  constructor(@InjectQueue('emails-dlq') private readonly dlq: Queue) { super(); }

  async process(job: Job): Promise<void> {
    // Idempotent work goes here; a thrown error counts as a failed attempt.
  }

  @OnWorkerEvent('failed')
  async onFailed(job: Job | undefined, err: Error) {
    // 'failed' fires on every failed attempt; only act once retries are exhausted.
    if (!job || job.attemptsMade < (job.opts.attempts ?? 1)) return;
    await this.dlq.add('dead-letter',
      { originalId: job.id, name: job.name, data: job.data, reason: err.message, failedAt: Date.now() },
      { jobId: `dead-${job.id}` }, // deterministic id avoids duplicate copies
    );
  }
}

@Module({
  imports: [
    BullModule.forRoot({ connection: { host: 'redis.internal', port: 6379 } }),
    BullModule.registerQueue(
      { name: 'emails', defaultJobOptions: {
          attempts: 5,
          backoff: { type: 'exponential', delay: 2000 },
          removeOnComplete: { age: 3600, count: 1000 }, // short history for successes
          removeOnFail: { age: 14 * 24 * 3600 },         // keep failures 14 days for forensics
      } },
      { name: 'emails-dlq' }, // no worker: entries wait here until you inspect or replay them
    ),
  ],
  providers: [EmailProcessor],
})
export class EmailModule {}

Bounds Redis memory with removeOnComplete/removeOnFail age and count limits, and copies jobs that exhaust their retries into a self-managed dead-letter queue from an @OnWorkerEvent('failed') handler.

How should you set worker concurrency in BullMQ?

The concurrency option lets one worker process run several jobs at once, but they all share a single Node.js event loop. That helps I/O-bound jobs, because while one job waits on an HTTP call or a query, another can make progress. It does nothing for CPU-bound work. A job that spends 200 ms parsing or resizing blocks every other job in that process for those 200 ms. Raising concurrency there only adds latency and makes lock renewal late, which feeds the stalled-job problem covered next.

Approach Helps with Cost
Raise per-process concurrency I/O-bound jobs Shares one event loop and one connection pool
Add worker replicas Both I/O and CPU More containers, Redis connections and DB connections
Sandboxed processor (separate process) CPU-bound jobs, isolating crashes Startup and memory overhead per child, no normal Nest DI in the sandboxed file, harder debugging

Effective parallelism is concurrency × replicas. Size that number against the dependencies your jobs actually hit. Here is an illustrative estimate with assumed inputs. Take 4 replicas at concurrency 10, which gives 40 jobs in flight. If each job makes one call to a partner API that takes 500 ms, you send about 80 requests per second. Against an assumed 20 req/s limit, that is four times too many. If each replica's database pool holds 5 connections, then 10 concurrent jobs per process will queue on the pool rather than run in parallel.

The worker-level limiter (max jobs per duration) is enforced through Redis across every worker on the queue. It is scoped to the queue, not to a downstream service. If one queue calls two APIs with different limits, the limiter has to match the stricter one. Splitting queues by dependency lets each queue carry its own limit. The cost is more queues to monitor, and multi-step work becomes job chains that are harder to reason about.

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

// Assumed: 4 replicas, partner API limit of 20 req/s, DB pool of 5 per replica.
// Effective parallelism = concurrency x replicas.

// Queue split by dependency: this queue only calls the partner API.
@Processor('partner-sync', {
  // I/O-bound: jobs mostly wait on HTTP, so several can share one event loop.
  concurrency: 10,
  // Enforced through Redis across ALL workers on this queue, not per replica:
  // at most 20 jobs start per 1000 ms, matching the partner's limit.
  limiter: { max: 20, duration: 1000 },
})
export class PartnerSyncProcessor extends WorkerHost {
  async process(job: Job<{ accountId: string }>): Promise<void> {
    // one outbound call per job, so jobs/s roughly equals req/s
  }
}

// Separate queue for DB-heavy work, sized to the pool rather than an API limit.
@Processor('report-build', {
  // Pool holds 5 connections per replica; more concurrency would only
  // queue jobs on the pool. 5 x 4 replicas = 20 jobs in flight.
  concurrency: 5,
})
export class ReportBuildProcessor extends WorkerHost {
  async process(job: Job<{ reportId: string }>): Promise<void> {
    // queries against the database
  }
}

Two NestJS BullMQ processors split by downstream dependency: the API-bound queue uses a queue-wide limiter set to the partner's limit, and the DB-bound queue sets concurrency to match the per-replica connection pool, using assumed inputs.

Why do BullMQ jobs stall and run twice?

Each active job holds a lock in Redis. The worker sets it when it picks up the job and renews it on a timer for as long as the processor runs. The lock duration sets how long the lock lasts without renewal. Renewal fires well before expiry, so a healthy worker never lets a lock lapse.

That renewal timer runs on the same event loop as your processor. If a job runs synchronous code for longer than the lock duration, such as a large JSON.parse, image resizing or a tight loop over a big array, the timer can't fire and the lock expires. Every few seconds, set by the stalled check interval, workers look for active jobs whose lock is gone and mark them stalled. A stalled job moves back to waiting and another worker picks it up. If the job has already stalled more times than the max stalled count, it is failed instead. Meanwhile the original worker is often still running, so the job executes twice. When the original worker finishes, it typically gets a lock error instead of a clean completion.

High concurrency makes this worse because every concurrent job shares one event loop. Many short synchronous sections can add up to a long block.

Raising the lock duration hides the symptom, but it also slows detection of workers that actually crashed. Fix the cause instead:

  • Move CPU-heavy work off the event loop with BullMQ's sandboxed processors or worker threads.
  • Split large jobs into smaller ones so each one finishes well within the lock duration.
  • Keep processors idempotent so the duplicate runs that remain have no harmful effect.

How do you shut down a NestJS BullMQ worker gracefully?

Nest only runs lifecycle hooks on a signal if you opt in. Call app.enableShutdownHooks() in main.ts before app.listen() or app.init(). Without it, SIGTERM kills the process immediately, and every active job is abandoned until it is recovered as stalled.

With hooks enabled, close the worker in onModuleDestroy. Nest runs that hook before beforeApplicationShutdown and onApplicationShutdown. Calling worker.close() stops the worker from fetching new jobs and waits for active ones to finish. Only then should any Redis connection you manage yourself be quit, in onApplicationShutdown. If you reverse that order, in-flight jobs fail when they try to mark themselves complete. Passing true to close() forces an immediate close, so reserve it for a deliberate hard stop.

Check what your installed @nestjs/bullmq version already closes for workers it creates through @Processor, rather than assuming. Read its source in node_modules, or test it directly:

  1. Enqueue a job that sleeps for 30 seconds.
  2. Send kill -TERM <pid> while the job is running.
  3. Confirm the job completes and the process then exits on its own.

The orchestrator's termination grace period must be longer than your longest expected job. When the grace period runs out, the process is killed, and the job runs again after stall detection. Do not solve this by raising the grace period to many minutes. Every rolling deploy and scale-down waits that long per pod. Instead, break long work into resumable steps, or checkpoint progress into job data with job.updateData(), so a restarted job continues where it stopped.

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

BullMQ is a poor fit when the work must commit or roll back with the request's database transaction, because a Redis enqueue can succeed while the transaction fails. It also struggles with strict global ordering, since parallel workers and retries reorder jobs. It cannot give exactly-once execution, because retries and stalls can always run a job twice. Batch work that runs for hours fights the shutdown and stall behaviour described above. BullMQ also requires Redis with persistence enabled and an eviction policy that never drops keys, so skip it if nobody will operate that. Finally, if many independent consumers need to replay the same events, you want a log, not a queue.

Option Good fit Main trade-off
In-process async work Best-effort side effects Lost on crash or deploy
Database job table Transactional enqueue, modest volume Polling and lock load on the database
Cron or scheduled jobs Periodic sweeps Coarse latency, overlapping runs
Log-based stream Fan-out, replay, per-key ordering Heavier operations, offset management
Managed cloud queue No broker to operate Provider limits, less control over retries

Setup inside Nest takes minutes. The real cost is idempotency, concurrency sizing, shutdown wiring and observability. Budget engineering time for those, not for the module import.

Observability checklist

  • Listen to completed, failed, stalled and error events. An unhandled error hides Redis connection problems.
  • Track waiting, active and failed counts, plus the age of the oldest waiting job.
  • Alert on a growing backlog and on repeated stalls, not on single failures. Retries absorb one-off errors, while trends point to real capacity or shutdown 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.