Skip to main contentClaim $5 in free credit — one-time, per account. Claim $5 free
Krova CloudKrova Cloud
Multi-Tenant SaaS Architecture

BullMQ Job Cancellation: A Request Is Not a Stopped Job

A cancellation receipt doesn't prove a tenant job stopped. Separate durable intent, worker interruption, retries and the business outcome before marking it cancelled.

RB
Rohit Bhadani6 min read
Share
Multi-Tenant SaaS Architecture cover with BullMQ Job Cancellation headline, request versus stopped message, practical subtitle, and frosted-glass job cards, worker and pause tile.

Imagine a customer cancelling a large report while it waits behind other tenants' jobs. Your API sends a cancellation message and changes the button to “Cancelled.” A worker starts the report a moment later. The button made a stronger promise than the system could verify.

Record cancellation intent durably, ask active work to stop, and report cancellation as complete only after the worker and business outcome have been reconciled. In BullMQ, interrupting active work and preventing future work are separate responsibilities. A signal alone isn't a durable instruction to every later attempt.

This guide uses a hypothetical tenant report and current BullMQ documentation checked on 22 November 2026. Verify the installed package version, worker implementation and supported APIs before applying the guidance; it isn't a claim that every deployed BullMQ version has the same interfaces.

Find out what your acknowledgement actually means

BullMQ's cancellation guide describes a cooperative mechanism: the processor observes an AbortSignal and performs appropriate cleanup. Work that never checks the signal, or never passes it into an abortable operation, can continue.

There is also a process boundary. The cross-worker cancellation guide explains that worker.cancelJob(jobId) acts on work running in that worker process. An API process needs a supported way to reach the worker that actually owns the job. The current Relay example provides one such route.

Read that route's receipt carefully: delivery to a worker inbox does not confirm that the owning worker stopped the job. The documented mechanism applies to running jobs; a request received while a job isn't running can have no effect. This is the gap our imagined queued report falls into.

Give the product a cancellation contract

Before adding an endpoint, define what the customer can reasonably cancel. For a generated report, the boundary might be publication of the final download. For a job that submits an external payment, cancellation has a different meaning after the remote provider accepts it. Write that boundary down with the application owner.

The following state vocabulary is a proposed application design, not a set of BullMQ states. Keep it in your durable business-job record alongside the tenant and operation identity:

Application observationWhat the interface can say
Cancellation request stored; work outcome unresolvedCancellation requested.
Worker has observed the request and is cleaning upStopping; outcome still being checked.
Relevant work stopped, with no remaining effect requiring reconciliationCancelled.
Final operation already completedCompleted before cancellation took effect.
External outcome or cleanup cannot be establishedNeeds reconciliation.

A queue's failed state and the product's cancelled outcome answer different questions. Preserve both. An expected customer cancellation shouldn't become an unexplained processing failure, and an unexplained failure shouldn't be relabelled as a successful cancellation.

Keep the decision after the message disappears

For the hypothetical service, authorize cancellation against the authenticated tenant and its job before writing anything. Possession of a job ID isn't permission to cancel it. Repeated requests for the same operation should return its existing cancellation status rather than create another operation.

Proposed application protocol — not runnable BullMQ code

API:
  authorize caller against tenant + business job
  serialize cancellation with the job's terminal-state transition
  persist cancel_requested, or return the established terminal outcome
  arrange delivery of an interruption request to active workers
  return the durable status reference

Worker:
  read the durable cancellation decision when an attempt starts
  check again at defined safe boundaries during work
  stop further work and clean up when cancellation is observed
  reconcile any uncertain external effect
  record the terminal business outcome under concurrency control

“Serialize” needs a real implementation: for example, a database transaction and conditional state update that both completion and cancellation follow. Don't implement it as two unrelated reads followed by unconditional writes. Keep the durable write and message delivery recoverable as well; if a separate broker is involved, use a transactional outbox or equivalent recovery process. Krova's job-status guide covers durable acceptance and a status reference.

The durable decision lets a later attempt discover that work is no longer wanted even if it missed the interruption message. Define how workers recover that decision when storage is unavailable. If the decision can't be read, silently assuming “continue” would undermine the cancellation contract.

Choose the retry outcome deliberately

A processor that stops by throwing a normal error may be retried when attempts remain. BullMQ's stop-retrying pattern documents UnrecoverableError for an unrecoverable failure, overriding automatic retry attempts. Use the installed version's documented permanent-cancellation path when that is the intended outcome; don't turn unrelated transient errors into permanent failures.

That controls queue retry behavior. It doesn't prevent an administrator or another code path from creating new work for the same business operation. Make every execution path consult the durable decision, and specify what an explicit “start a new report” action means after cancellation.

Deleting the job record is a different action. BullMQ's removal documentation says locked active jobs cannot be removed. Don't bypass the lock or delete backing-store records to make the interface look finished. Retain enough evidence to explain what actually happened.

Resolve the race at the business boundary

Return to the report. Checking a cancellation flag before uploading a result leaves a race: cancellation can arrive after the check but before publication. Choose which transition wins and implement that decision at the place that controls visibility. For example, keep an uploaded file private until the application authorizes publishing its reference under the same state-transition rules.

A remote side effect needs more care. Changing a local row can't atomically undo a request another system already accepted. Use the downstream service's supported cancellation or reconciliation process, and keep an uncertain result unresolved until verified. An aborted client request isn't proof that the remote action never happened.

Also distinguish user intent from infrastructure failure. BullMQ documents separate lock-loss handling in its cancellation guide. Don't translate every aborted signal into a customer cancellation; record the cause and reconcile queue ownership and durable business state.

Rehearse the cases the button hides

Use disposable tenants, test outputs and a queue isolated from production. These are proposed acceptance checks, not tests performed for this article:

  1. Request cancellation while the report is waiting, then let a worker claim it. Verify that the durable decision prevents unwanted work.
  2. Request cancellation during a bounded batch, with retry attempts configured. Confirm cleanup and the intended retry outcome.
  3. Deliver the request to a different process, delay delivery, and repeat it. Inspect durable intent, worker observation and final outcome separately.
  4. Race cancellation against publication. Check the documented winner and ensure the interface doesn't report contradictory terminal states.
  5. Attempt cancellation as another tenant, then make downstream completion uncertain. Confirm access is refused in the first case and reconciliation remains visible in the second.

Keep the job ID, tenant scope, request time, worker observation, attempt identity and final effect in restricted operational records. Avoid putting report contents or credentials into logs. If customers are waiting even before they cancel, Krova's tenant queue-wait guide addresses fairness and capacity as a separate problem.

Your next step is to name one job's irreversible boundary and define what “Cancelled” will prove. Then test the queued-to-running race before changing the button. That turns cancellation from a reassuring label into a contract you can inspect.

Rehearse tenant workers on a Cube

Use a self-managed Krova Cube for an isolated Linux test environment. You operate the queue, durable state and recovery logic; the VM doesn't supply the application's cancellation guarantees.

Creation context: This AI-assisted article uses linked primary documentation and a hypothetical report service. The protocol and rehearsal are design guidance, not a tested implementation or a customer incident. No personal testing or human approval by the bylined author is claimed. The cover is an AI-generated illustration.

For AI agents:llms.txtsitemap

Related posts