{"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":"http","errorClass":"BadRequestException","httpStatus":400,"severity":"warning","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/199723261c6ffa897fec8ccdaea6359e39c37cc3/server/src/services/queue.service.ts#L140-L176","documentation":"Thrown by QueueService.update when dto.isPaused === true AND name === QueueName.BackgroundTask. The BackgroundTask queue runs essential housekeeping (cleanup, sidecar writes, etc.) and must never be paused, so the guard hard-rejects the request. BadRequestException -> HTTP 400.","triggerScenarios":"PUT /admin/queues/backgroundTask with body { isPaused: true }; a bulk 'pause all queues' client loop that includes BackgroundTask.","commonSituations":"Automation script iterating over all QueueName values to pause them; admin UI 'pause all' button without an exclusion list; misunderstanding that BackgroundTask is special.","solutions":["Exclude QueueName.BackgroundTask from any pause-all logic.","Filter the queue list client-side before issuing pause requests: skip 'backgroundTask'.","If BackgroundTask is overloaded, scale workers instead of pausing the queue."],"exampleFix":"// before\nif (name === QueueName.BackgroundTask) {\n  throw new BadRequestException(`The BackgroundTask queue cannot be paused`);\n}\n\n// client-side guard\nconst pausable = queueNames.filter((n) => n !== QueueName.BackgroundTask);\nawait Promise.all(pausable.map((n) => api.put(`/admin/queues/${n}`, { isPaused: true })));","handlingStrategy":"validation","validationCode":"// Never attempt to pause BackgroundTask.\nconst pausable = queueNames.filter((n) => n !== QueueName.BackgroundTask);\nfor (const name of pausable) {\n  await queueService.update(auth, name, { isPaused: true });\n}","typeGuard":"const isPausable = (name: QueueName): boolean => name !== QueueName.BackgroundTask;","tryCatchPattern":"try {\n  await queueService.update(auth, name, { isPaused: true });\n} catch (e) {\n  if (e instanceof BadRequestException && /BackgroundTask/i.test(e.message)) {\n    // expected: skip this queue\n    return;\n  }\n  throw e;\n}","preventionTips":["Hard-code an exclusion list for BackgroundTask in any pause-all automation.","Filter the queue list in the admin UI before showing pause toggles.","Document that BackgroundTask is intentionally unstoppable."],"tags":["queue","background-task","jobs","admin","nestjs","validation"],"backgroundTag":null,"analyzedSha":"199723261c6ffa897fec8ccdaea6359e39c37cc3","analyzedAt":"2026-08-12T04:54:27.085Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}