{"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/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/astro/src/env/vite-plugin-env.ts#L142-L178","documentation":"At dev/build time Astro validates every variable declared in `env.schema` against the actual environment. When one or more fail (missing value, or a value that does not satisfy the declared type) and this is not a type-generation-only sync run, it throws EnvInvalidVariables listing each invalid key, its declared type, and the specific validation errors.","triggerScenarios":"Declaring `STRIPE_KEY: envField.string({ access: 'secret' })` but never providing STRIPE_KEY; declaring a number or enum while the environment holds a non-matching string ('abc' for number, a value outside the enum); a required public variable missing at build time in CI; optional/required mismatches between schema and reality.","commonSituations":"A teammate cloning the repo without the project's .env file; CI or deployment platform missing configured secrets; renaming a variable in env.schema but not in the deployment environment; values quoted or formatted so the declared type rejects them.","solutions":["Set every listed variable where Astro reads it: .env (and .env.production) for local, deployment secrets/environment variables for CI and production.","If absence is a supported state, declare the variable optional (envField.string({ access: 'secret', optional: true })) and handle undefined in code.","Fix declared types to match reality - correct enum values, number where the value is numeric.","Add an env preflight step to CI that fails before the build when required variables are missing."],"exampleFix":"// before - required secret that is never set anywhere\nexport default defineConfig({\n  env: { schema: { STRIPE_KEY: envField.string({ access: 'secret' }) } },\n});\n\n// after - optional with an explicit server-side check\nexport default defineConfig({\n  env: { schema: { STRIPE_KEY: envField.string({ access: 'secret', optional: true }) } },\n});","handlingStrategy":"validation","validationCode":"// preflight before `astro build` in CI\nconst required = ['SECRET_API_KEY', 'PUBLIC_SITE_URL'];\nconst missing = required.filter((k) => !process.env[k]);\nif (missing.length) {\n  console.error('missing env vars:', missing.join(', '));\n  process.exit(1);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep .env.example in sync with env.schema and make onboarding copy it.","Declare variables optional only when absence is a supported state; otherwise keep them required so failures are loud.","Add an env preflight step to CI so missing variables fail before the Astro build, with a clear message."],"tags":["environment-variables","validation","env-schema","config"],"backgroundTag":"env-var-validation-failed","analyzedSha":"52e6c34790cc8ac4e69e6135ace06049867e5c4a","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}