{"record":{"id":"16b6dbbb0ccb3ebc","repo":"immich-app/immich","slug":"the-backgroundtask-queue-cannot-be-paused","errorCode":null,"errorMessage":"The BackgroundTask queue cannot be paused","messagePattern":"The BackgroundTask queue cannot be paused","errorType":"exception","errorClass":"BadRequestException","httpStatus":400,"severity":"error","filePath":"server/src/services/queue.service.ts","lineNumber":158,"sourceCode":"  }\n\n  async getAll(_auth: AuthDto): Promise<QueueResponseDto[]> {\n    return Promise.all(Object.values(QueueName).map((name) => this.getByName(name)));\n  }\n\n  async getAllLegacy(auth: AuthDto): Promise<QueuesResponseLegacyDto> {\n    const responses = await this.getAll(auth);\n    return mapQueuesLegacy(responses);\n  }\n\n  get(auth: AuthDto, name: QueueName): Promise<QueueResponseDto> {\n    return this.getByName(name);\n  }\n\n  async update(auth: AuthDto, name: QueueName, dto: QueueUpdateDto): Promise<QueueResponseDto> {\n    if (dto.isPaused === true) {\n      if (name === QueueName.BackgroundTask) {\n        throw new BadRequestException(`The BackgroundTask queue cannot be paused`);\n      }\n      await this.jobRepository.pause(name);\n    } else if (dto.isPaused === false) {\n      await this.jobRepository.resume(name);\n    }\n\n    return this.getByName(name);\n  }\n\n  searchJobs(auth: AuthDto, name: QueueName, dto: QueueJobSearchDto): Promise<QueueJobResponseDto[]> {\n    return this.jobRepository.searchJobs(name, dto);\n  }\n\n  async emptyQueue(auth: AuthDto, name: QueueName, dto: QueueDeleteDto) {\n    await this.jobRepository.empty(name);\n    if (dto.failed) {\n      await this.jobRepository.clear(name, QueueCleanType.Failed);\n    }","sourceCodeStart":140,"sourceCodeEnd":176,"githubUrl":"https://github.com/immich-app/immich/blob/e55ac299a4ec7cb372e35dbf2c6c05ee9ce77f6c/server/src/services/queue.service.ts#L140-L176","documentation":"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.","triggerScenarios":"PUT/PATCH to the queue endpoint (or `queueService.update`) with `QueueName.BackgroundTask` and body `{\"isPaused\": true}`.","commonSituations":"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.","solutions":["Pause a specific queue other than BackgroundTask instead","Use the job control endpoints for individual job types rather than pausing the whole BackgroundTask queue","If you truly need to stop background work, stop the server/microservice worker rather than pausing the queue","Remove `isPaused: true` for BackgroundTask from automation configs"],"exampleFix":"// before\nawait api.updateQueue('backgroundTask', { isPaused: true }); // throws\n// after\nawait api.updateQueue('thumbnailGeneration', { isPaused: true }); // pause a specific queue","handlingStrategy":"validation","validationCode":"if (name === 'backgroundTask' && dto.isPaused === true) {\n  throw new InvalidQueueOperation(name);\n}","typeGuard":"function canPause(name: QueueName): boolean {\n  return name !== QueueName.BackgroundTask;\n}","tryCatchPattern":"try {\n  await queueService.update(auth, name, { isPaused: true });\n} catch (e) {\n  if (e instanceof BadRequestException && /cannot be paused/.test(e.message)) {\n    logger.warn(`Queue ${name} cannot be paused`);\n  } else throw e;\n}","preventionTips":["Exclude BackgroundTask when iterating queues to pause","Model queue pausability in your client config/UI","Prefer stopping workers over pausing background processing"],"tags":["queue","rest","unsupported-operation"],"backgroundTag":"unsupported-operation","analyzedSha":"e55ac299a4ec7cb372e35dbf2c6c05ee9ce77f6c","analyzedAt":"2026-09-15T07:20:19.675Z","contentChangedAt":"2026-09-15T07:20:19.675Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}