immich-app/immich · critical · Error

Invalid worker(s) found: ${workers.join(',')}

Error message

Invalid worker(s) found: ${workers.join(',')}

What it means

After env validation, getEnv() computes the effective worker set from IMMICH_WORKERS_INCLUDE minus IMMICH_WORKERS_EXCLUDE and checks each against WORKER_TYPES. Any unknown value throws Error('Invalid worker(s) found: <list>'). This guards against misconfigured worker selection at startup.

Source

Thrown at server/src/repositories/config.repository.ts:190

const getEnv = (): EnvData => {
  const parseResult = EnvSchema.safeParse(process.env);
  if (!parseResult.success) {
    const messages = ['Invalid environment variables: '];
    for (const issue of parseResult.error.issues) {
      const path = issue.path.join('.');
      messages.push(`  - [${path}] ${issue.message}`);
    }
    throw new Error(messages.join('\n'));
  }
  const dto = parseResult.data;

  const includedWorkers = asSet(dto.IMMICH_WORKERS_INCLUDE, [ImmichWorker.Api, ImmichWorker.Microservices]);
  const excludedWorkers = asSet(dto.IMMICH_WORKERS_EXCLUDE, []);
  const workers = [...setDifference(includedWorkers, excludedWorkers)];
  for (const worker of workers) {
    if (!WORKER_TYPES.has(worker)) {
      throw new Error(`Invalid worker(s) found: ${workers.join(',')}`);
    }
  }

  const environment = dto.IMMICH_ENV || ImmichEnvironment.Production;
  const isProd = environment === ImmichEnvironment.Production;
  const buildFolder = dto.IMMICH_BUILD_DATA || '/build';
  const folders = {
    geodata: join(buildFolder, 'geodata'),
    web: join(buildFolder, 'www'),
  };

  let redisConfig = {
    host: dto.REDIS_HOSTNAME || 'redis',
    port: dto.REDIS_PORT || 6379,
    db: dto.REDIS_DBINDEX || 0,
    username: dto.REDIS_USERNAME || undefined,
    password: dto.REDIS_PASSWORD || undefined,
    path: dto.REDIS_SOCKET || undefined,

View on GitHub (pinned to 199723261c)

Solutions

1. Compare the listed workers to the current ImmichWorker enum and correct any typo/renamed value.
2. Remove unknown entries from IMMICH_WORKERS_INCLUDE/EXCLUDE.
3. Leave both vars unset to use the defaults (api + microservices).

import { ImmichWorker } from '@immich/sdk';
const VALID = new Set(Object.values(ImmichWorker));
const requested = (process.env.IMMICH_WORKERS_INCLUDE ?? '').split(',').filter(Boolean);
const bad = requested.filter((w) => !VALID.has(w as ImmichWorker));
if (bad.length) throw new Error(`Unknown workers: ${bad.join(', ')}`);

const isWorker = (v: string): v is ImmichWorker =>
  new Set(Object.values(ImmichWorker)).has(v as ImmichWorker);

When it happens

Trigger: Setting IMMICH_WORKERS_INCLUDE or IMMICH_WORKERS_EXCLUDE to a comma-separated list containing a worker name that is not a valid ImmichWorker enum value.

Common situations: Typo in a worker name (e.g. microservices vs microservice); referencing a worker removed/renamed in a newer version; copy-pasting a stale list from old docs.

Related errors

• Invalid environment variables: \n - [${path}] ${issue.messa
• Invalid telemetry found: ${telemetry}
• Failed to decode redis options
• Unable to determine worker type
• Failed to read helmet file: ${helmetFile}

AI-assisted analysis of immich-app/immich@199723261c (2026-08-12). Data as JSON: /api/errors/44311465910e1622. Report an issue: GitHub.