immich-app/immich · critical · Error

Invalid environment variables: \n - [${path}] ${issue.messa

Error message

Invalid environment variables: \n  - [${path}] ${issue.message}

What it means

getEnv() runs EnvSchema.safeParse(process.env) (zod). On failure it builds a multi-line message listing every issue as [path] message and throws an Error. The message shows exactly which environment variables failed validation. This is the central env-var gate for server startup.

Source

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

        join(__dirname, '..', '..', 'helmet.json')
      : helmetFile;

  try {
    return JSON.parse(readFileSync(helmetFile).toString()) as HelmetOptions;
  } catch (error) {
    throw new Error(`Failed to read helmet file: ${helmetFile}`, { cause: error });
  }
};

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'),

View on GitHub (pinned to 199723261c)

Solutions

1. Read the error message: each [path] message line names the offending env var and why it failed.
2. Set the listed env vars to valid values (correct type/enum) in your env/compose file.
3. Re-deploy/restart and confirm process.env actually contains the values (check the entrypoint/shell).

import { z } from 'zod';
// mirror the subset of required vars you depend on
const probe = z.object({ DB_URL: z.string().url().optional(), REDIS_PORT: z.coerce.number().optional() });
const r = probe.safeParse(process.env);
if (!r.success) console.error(r.error.flatten());

When it happens

Trigger: Booting the server with one or more env vars missing, wrong type, or out of the allowed enum range — e.g. missing required DB/Redis vars, non-numeric port, or an enum value Immich does not recognize.

Common situations: Fresh deploy missing required vars; .env not loaded in the process; typo in a var name; value drift after an upgrade that renamed/added required vars.

Related errors

• Invalid worker(s) found: ${workers.join(',')}
• Invalid telemetry found: ${telemetry}
• Failed to decode redis options
• Invalid system config:
• Failed to read helmet file: ${helmetFile}

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