{"record":{"id":"e74e9a24e0baa4e0","repo":"withastro/astro","slug":"envinvalidvariables","errorCode":"EnvInvalidVariables","errorMessage":"The following environment variables defined in `env.schema` are invalid:\n\n${errors}","messagePattern":"The following environment variables defined in `env\\.schema` are invalid:\n\n(.+?)","errorType":"exception","errorClass":"AstroError","httpStatus":null,"severity":"error","filePath":"packages/astro/src/env/vite-plugin-env.ts","lineNumber":160,"sourceCode":"\tfor (const [key, options] of Object.entries(schema)) {\n\t\tconst variable = loadedEnv[key] === '' ? undefined : loadedEnv[key];\n\n\t\tif (options.access === 'secret' && !validateSecrets) {\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst result = validateEnvVariable(variable, options);\n\t\tconst type = getEnvFieldType(options);\n\t\tif (!result.ok) {\n\t\t\tinvalid.push({ key, type, errors: result.errors });\n\t\t\t// We don't do anything with validated secrets so we don't store them\n\t\t} else if (options.access === 'public') {\n\t\t\tvalid.push({ key, value: result.value, type, context: options.context });\n\t\t}\n\t}\n\n\tif (invalid.length > 0 && !sync) {\n\t\tthrow new AstroError({\n\t\t\t...AstroErrorData.EnvInvalidVariables,\n\t\t\tmessage: AstroErrorData.EnvInvalidVariables.message(invalidVariablesToError(invalid)),\n\t\t});\n\t}\n\n\treturn valid;\n}\n\nlet cachedServerTemplate: string | undefined;\n\nfunction getTemplates({\n\tschema,\n\tvalidatedVariables,\n\tloadedEnv,\n}: {\n\tschema: EnvSchema;\n\tvalidatedVariables: Array<ValidVariable>;\n\tloadedEnv: Record<string, string> | null;","sourceCodeStart":142,"sourceCodeEnd":178,"githubUrl":"https://github.com/withastro/astro/blob/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/astro/src/env/vite-plugin-env.ts#L142-L178","documentation":"During the build (non-sync mode), Astro validates every variable declared in `env.schema` against the loaded environment. Any variable whose validator returns `result.ok === false` is collected into an `invalid` list, and if that list is non-empty at the end, Astro aborts the build with `EnvInvalidVariables` listing each failing key, its declared type, and the validator errors.","triggerScenarios":"An env variable declared in `env.schema` is missing, malformed, or fails its declared type validator at build time — e.g. `env.number('PORT')` when PORT is unset or non-numeric, or `env.enum(...)` when the value isn't one of the allowed choices. Suppressed only when `sync: true` is set.","commonSituations":"Forgetting to set a required env var in CI or a deploy target; a `.env` file not loaded because `loadEnv`/`envDir` is misconfigured; a type mismatch after changing a variable's schema type; a secret that's empty or whitespace in production.","solutions":["Read the error's per-key list and set each missing/invalid variable to a value that satisfies its declared type in the target environment.","If a value is genuinely optional, give the schema entry a default or make validation tolerant per the env.schema API.","Confirm `.env` is discoverable: check `envDir` and that Vite's `loadEnv` is picking up the file for the current mode.","Re-run `astro build`/`astro dev` after fixing to confirm the validator passes."],"exampleFix":"// before\nexport default defineConfig({\n  env: { schema: { PORT: env.number() } }  // build fails if PORT unset\n})\n\n// after — supply a default so validation passes when unset\nexport default defineConfig({\n  env: { schema: { PORT: env.number({ default: 4321 }) } } })","handlingStrategy":"validation","validationCode":"import { loadEnv } from 'vite';\n// Pre-flight: check every schema var resolves and validates before build.\nfunction preflightEnv(schema, mode, envDir) {\n  const env = loadEnv(mode, envDir, '');\n  const missing = [];\n  for (const [key, opt] of Object.entries(schema)) {\n    if (env[key] === undefined && opt.access !== 'public') missing.push(key);\n  }\n  return missing;\n}","typeGuard":"null","tryCatchPattern":"null","preventionTips":["Provide defaults for optional env vars in env.schema.","Document required env vars in the project README and CI setup.","Run `astro build` locally with the same mode/env as production before deploy."],"tags":["env","config","build","validation"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}