{"record":{"id":"93e8f6c2e688dae8","repo":"immich-app/immich","slug":"invalid-environment-variables","errorCode":null,"errorMessage":"Invalid environment variables: ","messagePattern":"Invalid environment variables: ","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"server/src/repositories/config.repository.ts","lineNumber":177,"sourceCode":"\n  helmetFile = helmetFile === 'true' ? join(import.meta.dirname, '..', '..', 'helmet.json') : helmetFile;\n\n  try {\n    return JSON.parse(readFileSync(helmetFile).toString()) as HelmetOptions;\n  } catch (error) {\n    throw new Error(`Failed to read helmet file: ${helmetFile}`, { cause: error });\n  }\n};\n\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'),","sourceCodeStart":159,"sourceCodeEnd":195,"githubUrl":"https://github.com/immich-app/immich/blob/e55ac299a4ec7cb372e35dbf2c6c05ee9ce77f6c/server/src/repositories/config.repository.ts#L159-L195","documentation":"getEnv validates process.env against a Zod schema (EnvSchema.safeParse). When any required or format-constrained environment variable fails validation, the server refuses to start and throws this error, appending one '  - [path] message' line per Zod issue so every offending variable is listed at once.","triggerScenarios":"Calling getEnv() (at config/repository initialization) with process.env missing required variables (e.g. DB_HOSTNAME, DB_PASSWORD, REDIS_HOSTNAME in non-URL mode) or variables with values that fail Zod checks (bad URLs, non-numeric ports, invalid enums like IMMICH_ENV not in {production,development}).","commonSituations":"Fresh deployments with an incomplete .env file; typo'd variable names so the schema sees them as missing; upgrading immich where new required env vars were introduced; docker-compose files missing env_file wiring; setting IMMICH_WORKERS_INCLUDE to a value outside the enum.","solutions":["Read the issue lines under the message — each names the exact variable and Zod reason — and fix or set those variables in your .env / compose environment","Use server/.env as a template and fill in all required values (DB_*, REDIS_*)","If upgrading, check the release notes/migrations for newly required environment variables","Test locally with the same env: run the server once with the exported env and read the first failing entry"],"exampleFix":"# before\nDB_HOSTNAME=  # empty/missing\n# after\nDB_HOSTNAME=database\nDB_USERNAME=postgres\nDB_PASSWORD=postgres\nDB_DATABASE_NAME=immich","handlingStrategy":"validation","validationCode":"import { EnvSchema } from 'server/src/schema';\nconst result = EnvSchema.safeParse(process.env);\nif (!result.success) {\n  for (const i of result.error.issues) console.error(`  - [${i.path.join('.')}] ${i.message}`);\n  process.exit(1);\n}","typeGuard":"const envIsValid = (env: NodeJS.ProcessEnv): env is NodeJS.ProcessEnv & Record<string, string> => EnvSchema.safeParse(env).success;","tryCatchPattern":"try { const config = getEnv(); } catch (e) { if ((e as Error).message.startsWith('Invalid environment variables:')) { console.error('Fix the listed env vars in .env / compose:'); console.error((e as Error).message); process.exit(1); } throw e; }","preventionTips":["Start from server/.env.example and fill every required key","Keep .env referenced in docker-compose via env_file so vars actually reach the container","After upgrading immich, re-run validation against the new EnvSchema before deploying","Never leave required DB_*/REDIS_* values empty — comment them out only if you truly use DB_URL/REDIS_URL modes"],"tags":["env","config","zod","validation","startup"],"backgroundTag":"invalid-env-var-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"}