Skip to content
Esc

noctcore-nestjs/worker-must-listen-failed

Every BullMQ new Worker(...) has a .on('failed', ...) listener in the same file.

When a BullMQ job throws, the worker moves it to the failed set, retries it if it has attempts left, and emits a failed event. That event is the only signal. With no listener, nothing reaches the logs or the error tracker: the email is never sent, the invoice is never generated, and the first person to notice is the customer who asks where it went.

Incorrect
import { Worker } from 'bullmq';
const mailWorker = new Worker('mail', sendMail, { connection });
Correct
import { Worker } from 'bullmq';
const mailWorker = new Worker('mail', sendMail, { connection });
mailWorker.on('failed', (job, err) => logger.error({ jobId: job?.id, err }, 'mail job failed'));
  • A new Worker(...) bound to a name (const worker, this.worker =, this.worker ??=, or a class field private worker = new Worker(...)) when no <name>.on('failed', ...) appears anywhere in the file. Names are resolved through scope: a listener on another function’s w, or on the this.worker of an unrelated class (a sibling subclass included), does not count.
  • A new Worker(...) written as a bare statement with no .on('failed', ...) chained on it: nothing can ever subscribe to it.
  • With requiredEvents, each listed event that has no listener.
  • A worker whose only listener is .once('failed', ...) or .prependOnceListener('failed', ...): it hears the first failure and misses every later one.
Incorrect
import { Worker } from 'bullmq';
export class MailService {
private worker = new Worker('mail', sendMail, { connection });
onModuleInit() {
this.worker.on('completed', (job) => logger.info({ jobId: job.id }, 'mail sent'));
}
}
Correct
import { Worker } from 'bullmq';
export class MailService {
private worker = new Worker('mail', sendMail, { connection });
onModuleInit() {
this.worker.on('completed', (job) => logger.info({ jobId: job.id }, 'mail sent'));
this.worker.on('failed', (job, err) => logger.error({ jobId: job?.id, err }, 'mail failed'));
}
}
  • A listener chained on the constructor: new Worker(...).on('failed', ...), alone or after other .on(...) calls.
  • A listener attached through the same binding anywhere in the file, before or after the worker, in any method of the class, with or without a non-null assertion (this.worker!.on(...)). .addListener('failed', ...) and .prependListener('failed', ...) count like .on.
  • A listener on this.worker in a base class or a subclass declared in the same file: the field is shared along the hierarchy, so an abstract base service that wires the listeners covers the worker its subclass builds. A const self = this alias reads the same field.
  • A worker held in a field of a class whose base class comes from another module, or is a declare class: that base may attach the listener where the rule cannot see. A worker in a local variable of such a class is still checked.
  • A listener whose event name is not a static string, such as worker.on(Events.Failed, ...) or an event from a loop: it may be the failed listener, so it counts for every event. A const holding a string (const FAILED = 'failed') is read, and 'failed' as const is too.
  • A worker that is returned, passed to a function, stored in another variable, object or array, or destructured (const { worker } = this): the listener can be attached where it ends up. A chained assignment (const worker = this.worker = new Worker(...)) binds both names, so a listener on either counts.
  • A NestJS @Processor class extending WorkerHost: Nest builds that worker, so there is no new Worker(...) to check, and an @OnWorkerEvent('failed') method is how it listens.
  • A Worker that is not imported from bullmq, such as the one from node:worker_threads, a local class of the same name, or a parameter that shadows the import. A renamed import (import { Worker as BullWorker } from 'bullmq') is followed.
  • A namespace import (import * as bullmq from 'bullmq') or require('bullmq').
Correct
import { Worker } from 'bullmq';
export function createMailWorker() {
return new Worker('mail', sendMail, { connection });
}
new Worker('reports', buildReport, { connection }).on('failed', (job, err) => {
logger.error({ jobId: job?.id, err }, 'report failed');
});
const exportWorker = new Worker('exports', runExport, { connection });
for (const event of ['failed', 'error'] as const) {
exportWorker.on(event, (...args) => logger.error({ event, args }, 'export worker event'));
}
Correct
import { Worker } from 'bullmq';
abstract class QueueWorker {
protected abstract worker: Worker;
onModuleInit() {
this.worker.on('failed', (job, err) => logger.error({ jobId: job?.id, err }, 'job failed'));
}
}
export class MailWorker extends QueueWorker {
protected worker = new Worker('mail', sendMail, { connection });
}
Option Type Default Meaning
requiredEvents string[] ['failed'] Events each worker needs a .on(event, ...) listener for. Replaces the default, so list failed too.
'noctcore-nestjs/worker-must-listen-failed': ['error', { requiredEvents: ['failed', 'error'] }]
Incorrect
// rule options: {"requiredEvents":["failed","error"]}
import { Worker } from 'bullmq';
const mailWorker = new Worker('mail', sendMail, { connection });
mailWorker.on('failed', (job, err) => logger.error({ jobId: job?.id, err }, 'mail job failed'));
Correct
// rule options: {"requiredEvents":["failed","error"]}
import { Worker } from 'bullmq';
const mailWorker = new Worker('mail', sendMail, { connection });
mailWorker.on('failed', (job, err) => logger.error({ jobId: job?.id, err }, 'mail job failed'));
mailWorker.on('error', (err) => logger.error({ err }, 'mail worker error'));

If your workers are built in one module and every listener is attached in another (a shared instrumentWorker(worker) helper is fine, since passing the worker counts), the rule cannot see across files and reports the worker. Export it through a function that attaches the listener, or turn the rule off for that module. If failures are observed some other way, such as a QueueEvents listener in a separate process, the rule reports workers you consider covered; turn it off in that case.