{"record":{"id":"8fb72a4d22e65dfd","repo":"alan2207/bulletproof-react","slug":"invalid-env-provided-the-following-variables-are-8fb72a","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/react-vite/src/config/env.ts","lineNumber":28,"sourceCode":"      .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 = Object.entries(import.meta.env).reduce<\n    Record<string, string>\n  >((acc, curr) => {\n    const [key, value] = curr;\n    if (key.startsWith('VITE_APP_')) {\n      acc[key.replace('VITE_APP_', '')] = value;\n    }\n    return acc;\n  }, {});\n\n  const parsedEnv = EnvSchema.safeParse(envVars);\n\n  if (!parsedEnv.success) {\n    throw new Error(\n      `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`,\n    );\n  }\n\n  return parsedEnv.data;\n};\n\nexport const env = createEnv();\n","sourceCodeStart":10,"sourceCodeEnd":42,"githubUrl":"https://github.com/alan2207/bulletproof-react/blob/9506629ed003a561c6627735480cce4994244bb4/apps/react-vite/src/config/env.ts#L10-L42","documentation":"createEnv() in apps/react-vite/src/config/env.ts validates a filtered subset of import.meta.env against a Zod schema. Only keys prefixed VITE_APP_ are collected (prefix stripped), then EnvSchema.safeParse runs; on failure it throws at module load. API_URL is required, so the app white-screens on `yarn dev` when VITE_APP_API_URL is absent or a value like ENABLE_API_MOCKING isn't exactly 'true'/'false'.","triggerScenarios":"Running apps/react-vite without VITE_APP_API_URL in .env.local; using the wrong prefix (e.g. REACT_APP_API_URL or API_URL without the VITE_APP_ prefix — Vite only exposes VITE_-prefixed vars, and this schema further requires VITE_APP_); setting VITE_APP_ENABLE_API_MOCKING to 'yes'/'1'/boolean; deploying without adding the VITE_APP_* vars to the build environment.","commonSituations":"Fresh clone without .env.example copied; env file named .env.production.local vs .env.local confusion; CI builds (Netlify/Vercel) missing the VITE_APP_API_URL build-time variable; migrating from CRA and keeping REACT_APP_ prefixes, which Vite silently drops from import.meta.env.","solutions":["Create apps/react-vite/.env.local with VITE_APP_API_URL=http://localhost:3000 (and VITE_APP_ENABLE_API_MOCKING=true/false as desired), then restart the dev server.","Ensure every variable uses the VITE_APP_ prefix — plain API_URL is never picked up by the reduce() filter in env.ts.","Match the error's listed keys against your .env.local; fix only the failing ones (e.g. ENABLE_API_MOCKING must be the string 'true' or 'false').","For hosted builds, add VITE_APP_API_URL to build-time environment variables and trigger a rebuild."],"exampleFix":"# before\n# apps/react-vite/.env.local\nAPI_URL=http://localhost:3000   # wrong prefix → not exposed → error\n\n# after\n# apps/react-vite/.env.local\nVITE_APP_API_URL=http://localhost:3000\nVITE_APP_ENABLE_API_MOCKING=false","handlingStrategy":"validation","validationCode":"// Fail with a clear message before the app boots\nconst needed = ['VITE_APP_API_URL'];\nconst missing = needed.filter((k) => !(k in import.meta.env));\nif (missing.length) {\n  throw new Error(`Missing VITE_APP_ vars: ${missing.join(', ')}`);\n}","typeGuard":"import { z } from 'zod';\nconst EnvSchema = z.object({\n  API_URL: z.string().url(),\n  ENABLE_API_MOCKING: z.enum(['true', 'false']).optional(),\n});\nconst isEnv = (o: unknown): o is z.infer<typeof EnvSchema> =>\n  EnvSchema.safeParse(o).success;","tryCatchPattern":"// module-scope throw: catch where env is first consumed, e.g. main.tsx\ntry {\n  const { env } = await import('@/config/env');\n} catch (e) {\n  document.body.innerHTML = `<pre>${(e as Error).message}</pre>`;\n  throw e;\n}","preventionTips":["Always prefix Vite-exposed vars with VITE_APP_ (this schema strips that exact prefix).","Copy .env.example to .env.local as the first setup step and commit the example file.","Set VITE_APP_* vars in the CI/host build settings — Vite inlines them at build time.","Add a lint/test that imports @/config/env in CI so a bad env fails the build, not production."],"tags":["environment-variables","vite","zod","validation","startup"],"backgroundTag":"missing-env-var","analyzedSha":"9506629ed003a561c6627735480cce4994244bb4","analyzedAt":"2026-08-27T06:11:26.302Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}