{"record":{"id":"5ca285d6177cc559","repo":"alan2207/bulletproof-react","slug":"invalid-env-provided-the-following-variables-are","errorCode":null,"errorMessage":"Invalid env provided.\nThe following variables are missing or invalid:\n${Object.entries(parsedEnv.error.flatten().fieldErrors)\n.map(([k, v]) => `- ${k}: ${v}`)\n.join('\\n')}\n","messagePattern":"Invalid env provided\\.\nThe following variables are missing or invalid:\n(.+?): (.+?)`\\)\n\\.join\\('\\\\n'\\)\\}\n","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"apps/nextjs-app/src/config/env.ts","lineNumber":26,"sourceCode":"      .string()\n      .refine((s) => s === 'true' || s === 'false')\n      .transform((s) => s === 'true')\n      .optional(),\n    APP_URL: z.string().optional().default('http://localhost:3000'),\n    APP_MOCK_API_PORT: z.string().optional().default('8080'),\n  });\n\n  const envVars = {\n    API_URL: process.env.NEXT_PUBLIC_API_URL,\n    ENABLE_API_MOCKING: process.env.NEXT_PUBLIC_ENABLE_API_MOCKING,\n    APP_URL: process.env.NEXT_PUBLIC_URL,\n    APP_MOCK_API_PORT: process.env.NEXT_PUBLIC_MOCK_API_PORT,\n  };\n\n  const parsedEnv = EnvSchema.safeParse(envVars);\n\n  if (!parsedEnv.success) {\n    throw new Error(\n      `Invalid env provided.\n  The following variables are missing or invalid:\n  ${Object.entries(parsedEnv.error.flatten().fieldErrors)\n    .map(([k, v]) => `- ${k}: ${v}`)\n    .join('\\n')}\n  `,\n    );\n  }\n\n  return parsedEnv.data ?? {};\n};\n\nexport const env = createEnv();\n","sourceCodeStart":8,"sourceCodeEnd":40,"githubUrl":"https://github.com/alan2207/bulletproof-react/blob/9506629ed003a561c6627735480cce4994244bb4/apps/nextjs-app/src/config/env.ts#L8-L40","documentation":"This error is thrown by the createEnv() factory in apps/nextjs-app/src/config/env.ts when Zod's EnvSchema.safeParse() fails on the process.env-derived variables. It is an application-defined fail-fast check that runs at module load (via the exported `env` constant), so a missing or invalid variable crashes the app/server at startup rather than at request time. The message body lists exactly which fields failed (e.g. API_URL required).","triggerScenarios":"Importing anything that transitively imports @/config/env (e.g. the api client) without setting the required env vars. Concretely: API_URL missing from process.env, ENABLE_API_MOCKING set to something other than the literal strings 'true'/'false', or a non-string value (e.g. a number) passed for API_URL. Typically happens when running `next dev`/`next build` without a populated .env.local, or in CI/preview deployments where the variable was never configured.","commonSituations":"Fresh clone without copying .env.example to .env.local; deploying to Vercel/Netlify and forgetting to add API_URL in the project env settings; renaming a variable in EnvSchema but not in the deployment; CI pipelines that only set NODE_ENV; accidentally quoting values as booleans in Docker Compose producing invalid ENABLE_API_MOCKING values.","solutions":["Create apps/nextjs-app/.env.local and set the required variable, e.g. API_URL=http://localhost:3000 (and NEXT_PUBLIC_ vars as needed), then restart the dev server.","Check the error message body: each `- KEY: [reason]` line names the failing variable — fix exactly those keys in your environment/CI settings.","If deploying, add API_URL (and any other listed keys) to your hosting provider's environment variables and redeploy.","If a variable is genuinely optional in your setup, mark it optional/defaulted in EnvSchema (like APP_URL) instead of leaving it required."],"exampleFix":"# before (.env.local missing or incomplete)\n# App crashes: Invalid env provided.\n\n# after\n# apps/nextjs-app/.env.local\nAPI_URL=http://localhost:3000\nNEXT_PUBLIC_ENABLE_API_MOCKING=false\nNEXT_PUBLIC_APP_URL=http://localhost:3000","handlingStrategy":"validation","validationCode":"// Run before importing app code that uses @/config/env\nimport { createEnv } from '@/config/env.schema'; // or inline the check\nconst required = ['API_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":"import { z } from 'zod';\nconst EnvSchema = z.object({\n  API_URL: z.string().url(),\n  ENABLE_API_MOCKING: z\n    .string()\n    .refine((s) => s === 'true' || s === 'false')\n    .optional(),\n});\nconst isEnv = (o: unknown): o is z.infer<typeof EnvSchema> =>\n  EnvSchema.safeParse(o).success;","tryCatchPattern":"// Env is parsed at module load; catch at the entrypoint/bootstrap level\ntry {\n  const { env } = await import('@/config/env');\n} catch (e) {\n  console.error((e as Error).message); // lists failing keys\n  process.exit(1);\n}","preventionTips":["Copy .env.example to .env.local immediately after cloning and fill required keys.","Keep a startup env checklist in CI that greps for required variables before `next build`.","Give every schema field an optional().default(...) where the var is environment-dependent, reserving required status for truly mandatory keys.","Fail builds early: run a tiny script that imports @/config/env as a prebuild step."],"tags":["environment-variables","zod","validation","nextjs","startup"],"backgroundTag":"missing-env-var","analyzedSha":"9506629ed003a561c6627735480cce4994244bb4","analyzedAt":"2026-08-27T06:11:26.302Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}