ErrorCode

Enum of error codes returned by BullMQ Lua scripts

Overview

The ErrorCode enum contains error codes that can be returned by BullMQ’s Lua scripts when operations fail.

Enum

enum ErrorCode {
  JobNotExist = -1,
  JobLockNotExist = -2,
  JobNotInState = -3,
  JobPendingChildren = -4,
  ParentJobNotExist = -5,
  JobLockMismatch = -6,
  ParentJobCannotBeReplaced = -7,
  JobBelongsToJobScheduler = -8,
  JobHasFailedChildren = -9,
  SchedulerJobIdCollision = -10,
  SchedulerJobSlotsBusy = -11,
}

Error Codes

JobNotExist

JobNotExist · -1

The specified job does not exist in Redis

This error occurs when trying to operate on a job that has been removed or never existed.

// Example: Trying to get a non-existent job
const job = await queue.getJob('non-existent-id');
// job will be undefined

JobLockNotExist

JobLockNotExist · -2

The job’s lock does not exist

This error indicates that the job is not locked, which can happen if:

• The lock expired
• The job was never locked
• Another worker stole the lock

JobNotInState

JobNotInState · -3

The job is not in the expected state for the requested operation

For example, trying to promote a job that’s not in the delayed state:

// This will fail if job is not delayed
await job.promote();

JobPendingChildren

JobPendingChildren · -4

The job still has pending children and cannot be processed

This occurs when trying to move a parent job to active while it still has unfinished children.

ParentJobNotExist

ParentJobNotExist · -5

The parent job specified does not exist

Occurs when creating a child job with a non-existent parent:

await queue.add('child', { data }, {
  parent: {
    id: 'non-existent-parent',
    queue: 'bull:parentQueue',
  },
});

JobLockMismatch

JobLockMismatch · -6

The provided lock token doesn’t match the job’s current lock

This prevents one worker from modifying a job locked by another worker.

ParentJobCannotBeReplaced

ParentJobCannotBeReplaced · -7

The parent job cannot be replaced while it has children

Occurs when trying to replace a job that has child dependencies.

JobBelongsToJobScheduler

JobBelongsToJobScheduler · -8

The job belongs to a job scheduler and cannot be modified directly

Jobs created by job schedulers (repeatable jobs) cannot be modified directly.

JobHasFailedChildren

JobHasFailedChildren · -9

The job cannot proceed because it has failed children

This error occurs when a parent job’s children have failed and the parent cannot continue.

SchedulerJobIdCollision

SchedulerJobIdCollision · -10

A job scheduler with this ID already exists

Occurs when trying to create a job scheduler with an ID that’s already in use.

SchedulerJobSlotsBusy

SchedulerJobSlotsBusy · -11

The job scheduler’s time slots are busy

This can occur when the scheduler is trying to create jobs but the slots are already occupied.

Usage

These error codes are typically returned by internal Lua scripts and converted to JavaScript errors. You generally won’t use these directly, but they may appear in error messages:

import { Job } from 'bullmq';

try {
  await job.promote();
} catch (error) {
  console.error('Failed to promote job:', error.message);
  // Error message may reference error codes
}

Handling Script Errors

When BullMQ operations fail, the errors usually include descriptive messages:

import { Queue } from 'bullmq';

const queue = new Queue('myQueue');

try {
  await queue.remove('job-id');
} catch (error) {
  if (error.message.includes('locked')) {
    console.log('Job is locked by another worker');
  } else if (error.message.includes('not exist')) {
    console.log('Job does not exist');
  }
}

Related

• UnrecoverableError - Error to fail jobs immediately
• RateLimitError - Error for rate limiting
• Job - Job class that may encounter these errors