{"record":{"id":"44311465910e1622","repo":"immich-app/immich","slug":"invalid-worker-s-found-workers-join","errorCode":null,"errorMessage":"Invalid worker(s) found: ${workers.join(',')}","messagePattern":"Invalid worker\\(s\\) found: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/src/repositories/config.repository.ts","lineNumber":186,"sourceCode":"\nconst getEnv = (): EnvData => {\n  const parseResult = EnvSchema.safeParse(process.env);\n  if (!parseResult.success) {\n    const messages = ['Invalid environment variables: '];\n    for (const issue of parseResult.error.issues) {\n      const path = issue.path.join('.');\n      messages.push(`  - [${path}] ${issue.message}`);\n    }\n    throw new Error(messages.join('\\n'));\n  }\n  const dto = parseResult.data;\n\n  const includedWorkers = asSet(dto.IMMICH_WORKERS_INCLUDE, [ImmichWorker.Api, ImmichWorker.Microservices]);\n  const excludedWorkers = asSet(dto.IMMICH_WORKERS_EXCLUDE, []);\n  const workers = [...setDifference(includedWorkers, excludedWorkers)];\n  for (const worker of workers) {\n    if (!WORKER_TYPES.has(worker)) {\n      throw new Error(`Invalid worker(s) found: ${workers.join(',')}`);\n    }\n  }\n\n  const environment = dto.IMMICH_ENV || ImmichEnvironment.Production;\n  const isProd = environment === ImmichEnvironment.Production;\n  const buildFolder = dto.IMMICH_BUILD_DATA || '/build';\n  const folders = {\n    geodata: join(buildFolder, 'geodata'),\n    web: join(buildFolder, 'www'),\n  };\n\n  let redisConfig = {\n    host: dto.REDIS_HOSTNAME || 'redis',\n    port: dto.REDIS_PORT || 6379,\n    db: dto.REDIS_DBINDEX || 0,\n    username: dto.REDIS_USERNAME || undefined,\n    password: dto.REDIS_PASSWORD || undefined,\n    path: dto.REDIS_SOCKET || undefined,","sourceCodeStart":168,"sourceCodeEnd":204,"githubUrl":"https://github.com/immich-app/immich/blob/e55ac299a4ec7cb372e35dbf2c6c05ee9ce77f6c/server/src/repositories/config.repository.ts#L168-L204","documentation":"After parsing IMMICH_WORKERS_INCLUDE/EXCLUDE into a set of worker names, getEnv verifies each resulting worker is a known ImmichWorker. If any computed worker is not in WORKER_TYPES, startup aborts with the comma-separated list of all offending workers.","triggerScenarios":"IMMICH_WORKERS_INCLUDE or IMMICH_WORKERS_EXCLUDE contains a value not in the ImmichWorker enum (e.g. 'api,worker', 'microservice', case-mismatched 'API'), so the set difference produces an unknown worker name.","commonSituations":"Users writing '-worker' or 'jobs' expecting background jobs; pluralizing 'microservices'; renaming after an immich version changed the worker enum; including an excluded-only name or an entirely wrong token in the comma list.","solutions":["Use only valid worker names: 'api' and 'microservices' (check the ImmichWorker enum in server/src for the exact set)","Fix casing/spelling: IMMICH_WORKERS_INCLUDE=api,microservices (lowercase, no spaces)","If the intent was to exclude a worker, set IMMICH_WORKERS_EXCLUDE=microservices instead of inventing names in INCLUDE","Upgrade/downgrade immich if a worker name existed in another version of the enum"],"exampleFix":"// before\nIMMICH_WORKERS_INCLUDE=api,worker\n// after\nIMMICH_WORKERS_INCLUDE=api,microservices","handlingStrategy":"validation","validationCode":"const WORKERS = new Set(['api', 'microservices']);\nconst requested = (process.env.IMMICH_WORKERS_INCLUDE ?? 'api,microservices').split(',').filter(Boolean);\nconst bad = requested.filter(w => !WORKERS.has(w));\nif (bad.length) throw new Error(`Unknown workers: ${bad.join(',')} — valid: ${[...WORKERS].join(',')}`);","typeGuard":"const isWorker = (w: string): w is 'api' | 'microservices' => w === 'api' || w === 'microservices';","tryCatchPattern":"try { start(); } catch (e) { if ((e as Error).message.startsWith('Invalid worker(s) found')) { console.error(`Valid workers are: api, microservices. Got: ${(e as Error).message}`); process.exit(1); } throw e; }","preventionTips":["Only use the exact enum values 'api' and 'microservices' (lowercase, singular)","To run one service only, combine INCLUDE and EXCLUDE rather than inventing names","Trim spaces around comma-separated values in .env files","Check the ImmichWorker enum for your immich version before scripting worker flags"],"tags":["config","env","workers","validation"],"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"}