immich-app/immich · error · BadRequestException

The BackgroundTask queue cannot be paused

Error message

The BackgroundTask queue cannot be paused

What it means

Queue.service's `update` rejects pausing the BackgroundTask queue outright. BackgroundTask processing is considered essential internal work, so the API intentionally forbids setting `isPaused: true` on it. Resuming (`isPaused: false`) remains allowed for all queues.

Solutions

1. Pause a specific queue other than BackgroundTask instead
2. Use the job control endpoints for individual job types rather than pausing the whole BackgroundTask queue
3. If you truly need to stop background work, stop the server/microservice worker rather than pausing the queue
4. Remove `isPaused: true` for BackgroundTask from automation configs

Example fix

// before
await api.updateQueue('backgroundTask', { isPaused: true }); // throws
// after
await api.updateQueue('thumbnailGeneration', { isPaused: true }); // pause a specific queue

if (name === 'backgroundTask' && dto.isPaused === true) {
  throw new InvalidQueueOperation(name);
}

function canPause(name: QueueName): boolean {
  return name !== QueueName.BackgroundTask;
}

try {
  await queueService.update(auth, name, { isPaused: true });
} catch (e) {
  if (e instanceof BadRequestException && /cannot be paused/.test(e.message)) {
    logger.warn(`Queue ${name} cannot be paused`);
  } else throw e;
}

When it happens

Trigger: PUT/PATCH to the queue endpoint (or `queueService.update`) with `QueueName.BackgroundTask` and body `{"isPaused": true}`.

Common situations: Admins trying to drain the system by pausing background jobs to reduce load; automation scripts pausing all queues indiscriminately; misunderstanding that BackgroundTask is pause-able like thumbnail/video queues.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Cannot unlink Android motion photos
• Invalid job name
• Job is already running
• Plugin not found
• Task with id not found

AI-assisted analysis of immich-app/immich@e55ac299a4 (2026-09-15). Data as JSON: /api/errors/16b6dbbb0ccb3ebc. Report an issue: GitHub.

Appendix: source

Thrown at server/src/services/queue.service.ts:158

  }

  async getAll(_auth: AuthDto): Promise<QueueResponseDto[]> {
    return Promise.all(Object.values(QueueName).map((name) => this.getByName(name)));
  }

  async getAllLegacy(auth: AuthDto): Promise<QueuesResponseLegacyDto> {
    const responses = await this.getAll(auth);
    return mapQueuesLegacy(responses);
  }

  get(auth: AuthDto, name: QueueName): Promise<QueueResponseDto> {
    return this.getByName(name);
  }

  async update(auth: AuthDto, name: QueueName, dto: QueueUpdateDto): Promise<QueueResponseDto> {
    if (dto.isPaused === true) {
      if (name === QueueName.BackgroundTask) {
        throw new BadRequestException(`The BackgroundTask queue cannot be paused`);
      }
      await this.jobRepository.pause(name);
    } else if (dto.isPaused === false) {
      await this.jobRepository.resume(name);
    }

    return this.getByName(name);
  }

  searchJobs(auth: AuthDto, name: QueueName, dto: QueueJobSearchDto): Promise<QueueJobResponseDto[]> {
    return this.jobRepository.searchJobs(name, dto);
  }

  async emptyQueue(auth: AuthDto, name: QueueName, dto: QueueDeleteDto) {
    await this.jobRepository.empty(name);
    if (dto.failed) {
      await this.jobRepository.clear(name, QueueCleanType.Failed);
    }

View on GitHub (pinned to e55ac299a4)