{"record":{"id":"6e1536cd15258ae0","repo":"immich-app/immich","slug":"skipping-unknown-job-name","errorCode":null,"errorMessage":"Skipping unknown job: \"${name}\"","messagePattern":"Skipping unknown job: \"(.+?)\"","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"server/src/repositories/job.repository.ts","lineNumber":140,"sourceCode":"      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) {\n    const worker = this.workers[queueName];\n    if (!worker) {\n      this.logger.warn(`Unable to set queue concurrency, worker not found: '${queueName}'`);\n      return;\n    }\n\n    worker.concurrency = concurrency;\n  }\n\n  async isActive(name: QueueName): Promise<boolean> {\n    const queue = this.getQueue(name);","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/immich-app/immich/blob/e55ac299a4ec7cb372e35dbf2c6c05ee9ce77f6c/server/src/repositories/job.repository.ts#L122-L158","documentation":"Job items dispatched to the queue are matched against the registered handlers map. If a job with the given name arrives with no registered handler, the repository logs this warning and returns JobStatus.Skipped instead of throwing. Usually means a job was enqueued under a name the running code doesn't know.","triggerScenarios":"run() receives a JobItem whose name is not a key in this.handlers — e.g. a job name from a newer/older Immich version, or the worker process lacks the module that registers the handler.","commonSituations":"Version skew: server upgraded but microservices container still running old image (or vice versa); stale jobs left in Redis from a previous version with removed job names; custom/renamed job names.","solutions":["Update all Immich containers to the same version so job names and handlers match","Clear stale jobs from the Redis queue (or let them drain/skip)","Verify the microservices process started with the full handler registry (check for startup errors in the worker)","Re-trigger the intended operation from the UI/API after upgrading"],"exampleFix":"// before: mixed versions\nIMMICH_VERSION: v1.90.0  # server\nIMMICH_VERSION: v1.89.0  # microservices\n// after\nIMMICH_VERSION: v1.90.0  # same tag for all services (use ${IMMICH_VERSION:-release})","handlingStrategy":"type-guard","validationCode":"const knownJobs: JobName[] = Object.values(JobName);\nfunction assertJobKnown(name: string): asserts name is JobName {\n  if (!knownJobs.includes(name as JobName)) {\n    throw new Error(`Unknown job name: ${name} — likely version skew between containers`);\n  }\n}","typeGuard":"function isKnownJob(name: string): name is JobName {\n  return name in (jobRepository as any).handlers;\n}","tryCatchPattern":"try {\n  const status = await jobRepository.run(jobItem);\n  if (status === JobStatus.Skipped) {\n    logger.warn(`Job ${jobItem.name} skipped: handler missing — update all services to the same version`);\n  }\n} catch (err) { logger.error(err); }","preventionTips":["Pin identical IMMICH_VERSION across all Immich containers","Flush stale Redis queues after major upgrades","Register every JobName handler in one module to keep the map exhaustive","Handle JobStatus.Skipped explicitly in callers"],"tags":["bullmq","jobs","version-skew"],"backgroundTag":"invalid-enum-value","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"}