{"record":{"id":"dc4e4cdee7993a37","repo":"immich-app/immich","slug":"no-microservices-worker-is-connected-background-jobs-will","errorCode":null,"errorMessage":"No microservices worker is connected. Background jobs will not be processed until one is running.","messagePattern":"No microservices worker is connected\\. Background jobs will not be processed until one is running\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"server/src/repositories/job.repository.ts","lineNumber":129,"sourceCode":"    clearInterval(this.workerWatcher);\n    this.workerWatcher = undefined;\n  }\n\n  private async checkWorkers() {\n    let isPresent: boolean;\n    try {\n      const suffix = `:w:${ImmichWorker.Microservices}`;\n      const workers = await this.getQueue(QueueName.BackgroundTask).getWorkers();\n      isPresent = workers.some((worker) => worker.rawname?.endsWith(suffix));\n    } catch {\n      return;\n    }\n\n    if (this.microservicesPresent !== isPresent) {\n      if (isPresent) {\n        this.logger.log('Microservices worker connected.');\n      } else {\n        this.logger.warn(\n          'No microservices worker is connected. Background jobs will not be processed until one is running.',\n        );\n      }\n    }\n    this.microservicesPresent = isPresent;\n  }\n\n  async run({ name, data }: JobItem) {\n    const item = this.handlers[name as JobName];\n    if (!item) {\n      this.logger.warn(`Skipping unknown job: \"${name}\"`);\n      return JobStatus.Skipped;\n    }\n\n    return item.handler(data);\n  }\n\n  setConcurrency(queueName: QueueName, concurrency: number) {","sourceCodeStart":111,"sourceCodeEnd":147,"githubUrl":"https://github.com/immich-app/immich/blob/e55ac299a4ec7cb372e35dbf2c6c05ee9ce77f6c/server/src/repositories/job.repository.ts#L111-L147","documentation":"The job repository watches for a connected microservices worker (the process that consumes BullMQ background jobs). When the presence transitions to absent, it warns that no worker is consuming jobs. API work continues but background jobs (thumbnailing, ML, backups) will queue indefinitely.","triggerScenarios":"checkWorkers (invoked from watchWorkers polling BullMQ clients) detects that previously-present microservices workers are gone, or none ever connected at startup.","commonSituations":"Running Immich with only the API server container (microservices container stopped/never started); microservices container crash-looping; Redis connectivity issues preventing worker registration; resource limits (OOM) killing the worker.","solutions":["Start the microservices service: docker compose up -d immich-microservices (or run 'npm run start:worker' in dev)","Check the microservices container logs for crash causes and fix (ML/Redis connection errors, OOM)","Verify Redis (or the configured queue driver) is reachable from both containers","Check container resource limits and increase memory if the worker is being OOM-killed"],"exampleFix":"// before (docker-compose.yml) — only server defined\nservices:\n  immich-server: ...\n// after\nservices:\n  immich-server: ...\n  immich-microservices:\n    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}\n    command: ['start-microservices.sh']\n    ...","handlingStrategy":"retry","validationCode":"// health check before assuming jobs will run\nconst redisOk = await new Promise(res => redis.ping().then(() => res(true)).catch(() => res(false)));\nconst workersPresent = await bullmqQueue.getWorkersCount();\nif (!redisOk || workersPresent === 0) {\n  throw new Error('No job workers connected — start immich-microservices and check Redis');\n}","typeGuard":null,"tryCatchPattern":"try {\n  await jobRepository.pause(QueueName.ThumbnailGeneration); // or gate submissions\n} catch (err) {\n  alert('No microservices worker: jobs will queue unprocessed');\n}","preventionTips":["Run both immich-server and immich-microservices containers with the same image tag","Monitor worker count via Redis/BullMQ metrics and alert on zero","Keep Redis reachable from all containers","Set memory limits high enough to avoid OOM-killing the worker"],"tags":["bullmq","redis","microservices","background-jobs"],"backgroundTag":"connection-refused","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"}