{"record":{"id":"c27268bb7774a405","repo":"immich-app/immich","slug":"unable-to-determine-worker-type","errorCode":null,"errorMessage":"Unable to determine worker type","messagePattern":"Unable to determine worker type","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/src/repositories/event.repository.ts","lineNumber":170,"sourceCode":"\n@Injectable()\nexport class EventRepository {\n  private emitHandlers: EmitHandlers = {};\n\n  constructor(\n    private moduleRef: ModuleRef,\n    private configRepository: ConfigRepository,\n    private logger: LoggingRepository,\n  ) {\n    this.logger.setContext(EventRepository.name);\n  }\n\n  setup({ services }: { services: (new (...args: any[]) => unknown)[] }) {\n    const reflector = this.moduleRef.get(Reflector, { strict: false });\n    const items: Item<EmitEvent>[] = [];\n    const worker = this.configRepository.getWorker();\n    if (!worker) {\n      throw new Error('Unable to determine worker type');\n    }\n\n    // discovery\n    for (const Service of services) {\n      const instance = this.moduleRef.get<any>(Service);\n      const ctx = Object.getPrototypeOf(instance);\n      for (const property of Object.getOwnPropertyNames(ctx)) {\n        const descriptor = Object.getOwnPropertyDescriptor(ctx, property);\n        if (!descriptor || descriptor.get || descriptor.set) {\n          continue;\n        }\n\n        const handler = instance[property];\n        if (typeof handler !== 'function') {\n          continue;\n        }\n\n        const event = reflector.get<EventConfig>(MetadataKey.EventConfig, handler);","sourceCodeStart":152,"sourceCodeEnd":188,"githubUrl":"https://github.com/immich-app/immich/blob/f48d4b332127ad365ba256108799ca8f571d2dd5/server/src/repositories/event.repository.ts#L152-L188","documentation":"During event repository setup, Immich discovers @OnEvent handlers by reflecting metadata across services, but first needs to know which worker (microservices, api, etc.) it is running as. If configRepository.getWorker() returns null/undefined — no worker role was configured in the environment — setup cannot decide which events apply and throws an ImmichStartupError.","triggerScenarios":"Starting the server process without the IMMICH_WORKERS (worker role) env var set, so getWorker() resolves to nothing; launching the app in a context where the worker configuration was not loaded.","commonSituations":"Custom systemd/pm2 setups that skip the official entrypoint; Kubernetes manifests missing the worker env var; running the server entrypoint directly with a stripped environment.","solutions":["Set the worker configuration env var (IMMICH_WORKERS, e.g. 'api' or 'microservices' or comma-separated) in the process environment","Start Immich through its official entrypoint/docker-compose so worker env defaults are applied","Verify with the app's env-dump (or getEnv) that the worker field is populated before Nest bootstrap","If embedding the app, explicitly configure ConfigRepository/env sources so getWorker() returns a valid role"],"exampleFix":"// before\nCMD [\"node\", \"dist/main\"]\n// after\nENV IMMICH_WORKERS=api,microservices\nCMD [\"node\", \"dist/main\"]","handlingStrategy":"validation","validationCode":"if (!process.env.IMMICH_WORKERS) {\n  throw new Error('IMMICH_WORKERS must be set (e.g. api,microservices)');\n}","typeGuard":"function workerIsConfigured(env: { workers?: string | null }): env is { workers: string } {\n  return typeof env.workers === 'string' && env.workers.length > 0;\n}","tryCatchPattern":"try {\n  eventRepo.setup({ services });\n} catch (e) {\n  if ((e as Error).message === 'Unable to determine worker type') {\n    process.env.IMMICH_WORKERS ??= 'api'; // apply default then retry once\n    eventRepo.setup({ services });\n  } else throw e;\n}","preventionTips":["Set IMMICH_WORKERS explicitly in every deployment manifest","Launch via the official entrypoint which defaults worker env","Validate env at process start with a schema before Nest bootstrap"],"tags":["configuration","startup","worker","env"],"backgroundTag":"missing-env-var","analyzedSha":"f48d4b332127ad365ba256108799ca8f571d2dd5","analyzedAt":"2026-09-15T07:20:19.675Z","contentChangedAt":"2026-09-15T07:20:19.675Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}