immich-app/immich · error

Unable to determine worker type

Error message

Unable to determine worker type

What it means

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.

Solutions

1. Set the worker configuration env var (IMMICH_WORKERS, e.g. 'api' or 'microservices' or comma-separated) in the process environment
2. Start Immich through its official entrypoint/docker-compose so worker env defaults are applied
3. Verify with the app's env-dump (or getEnv) that the worker field is populated before Nest bootstrap
4. If embedding the app, explicitly configure ConfigRepository/env sources so getWorker() returns a valid role

Example fix

// before
CMD ["node", "dist/main"]
// after
ENV IMMICH_WORKERS=api,microservices
CMD ["node", "dist/main"]

if (!process.env.IMMICH_WORKERS) {
  throw new Error('IMMICH_WORKERS must be set (e.g. api,microservices)');
}

function workerIsConfigured(env: { workers?: string | null }): env is { workers: string } {
  return typeof env.workers === 'string' && env.workers.length > 0;
}

try {
  eventRepo.setup({ services });
} catch (e) {
  if ((e as Error).message === 'Unable to determine worker type') {
    process.env.IMMICH_WORKERS ??= 'api'; // apply default then retry once
    eventRepo.setup({ services });
  } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Failed to add job handler for
• Failed to find job handler for Job.
• Invalid environment variables:
• Invalid environment variables: \n
• Detected an inconsistent media location. For more…

AI-assisted analysis of immich-app/immich@f48d4b3321 (2026-09-15). Data as JSON: /api/errors/c27268bb7774a405. Report an issue: GitHub.

Appendix: source

Thrown at server/src/repositories/event.repository.ts:170

@Injectable()
export class EventRepository {
  private emitHandlers: EmitHandlers = {};

  constructor(
    private moduleRef: ModuleRef,
    private configRepository: ConfigRepository,
    private logger: LoggingRepository,
  ) {
    this.logger.setContext(EventRepository.name);
  }

  setup({ services }: { services: (new (...args: any[]) => unknown)[] }) {
    const reflector = this.moduleRef.get(Reflector, { strict: false });
    const items: Item<EmitEvent>[] = [];
    const worker = this.configRepository.getWorker();
    if (!worker) {
      throw new Error('Unable to determine worker type');
    }

    // discovery
    for (const Service of services) {
      const instance = this.moduleRef.get<any>(Service);
      const ctx = Object.getPrototypeOf(instance);
      for (const property of Object.getOwnPropertyNames(ctx)) {
        const descriptor = Object.getOwnPropertyDescriptor(ctx, property);
        if (!descriptor || descriptor.get || descriptor.set) {
          continue;
        }

        const handler = instance[property];
        if (typeof handler !== 'function') {
          continue;
        }

        const event = reflector.get<EventConfig>(MetadataKey.EventConfig, handler);

View on GitHub (pinned to f48d4b3321)