{"record":{"id":"bf88ce63bb63de6d","repo":"immich-app/immich","slug":"invalid-environment-variables-n-path-i","errorCode":null,"errorMessage":"Invalid environment variables: \\n  - [${path}] ${issue.message}","messagePattern":"Invalid environment variables: \\\\n  - \\[(.+?)\\] (.+?)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"server/src/repositories/config.repository.ts","lineNumber":181,"sourceCode":"        join(__dirname, '..', '..', 'helmet.json')\n      : 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":163,"sourceCodeEnd":199,"githubUrl":"https://github.com/immich-app/immich/blob/199723261c6ffa897fec8ccdaea6359e39c37cc3/server/src/repositories/config.repository.ts#L163-L199","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the error message: each [path] message line names the offending env var and why it failed.","Set the listed env vars to valid values (correct type/enum) in your env/compose file.","Re-deploy/restart and confirm process.env actually contains the values (check the entrypoint/shell)."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"import { z } from 'zod';\n// mirror the subset of required vars you depend on\nconst probe = z.object({ DB_URL: z.string().url().optional(), REDIS_PORT: z.coerce.number().optional() });\nconst r = probe.safeParse(process.env);\nif (!r.success) console.error(r.error.flatten());","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep a checked-in example .env and diff against it before deploy.","Run a preflight that loads and zod-validates env at deploy time.","After upgrades, review the changelog for newly required/renamed env vars."],"tags":["configuration","environment","zod","validation","startup"],"backgroundTag":null,"analyzedSha":"199723261c6ffa897fec8ccdaea6359e39c37cc3","analyzedAt":"2026-08-12T04:54:27.085Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}