{"record":{"id":"a1e71292741bc91e","repo":"alan2207/bulletproof-react","slug":"invalid-env-provided-the-following-variables-are-a1e712","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-pages/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-pages/src/config/env.ts#L8-L40","documentation":"Identical fail-fast pattern to the nextjs-app variant: createEnv() in apps/nextjs-pages/src/config/env.ts throws at module load when EnvSchema.safeParse() rejects the env vars (API_URL required, ENABLE_API_MOCKING must be the literal 'true'/'false'). Because `env` is computed at import time, any route/component importing the config crashes the Pages Router build or request before rendering.","triggerScenarios":"Running `next dev`/`next build`/`next start` for apps/nextjs-pages without API_URL defined; setting ENABLE_API_MOCKING to '1', 'yes', or a boolean instead of 'true'/'false'; CI/preview environments lacking the NEXT_PUBLIC_* variables; SSR pages importing @/config/env during a build prerender pass with no env file present.","commonSituations":"Cloning the repo and only setting up apps/react-vite; deploying the pages app with env vars configured for the app-router app but not this one; Docker images built without baking in build-time NEXT_PUBLIC_ variables (which must exist at build time for client bundles).","solutions":["Create apps/nextjs-pages/.env.local with API_URL=http://localhost:3000 (plus NEXT_PUBLIC_ENABLE_API_MOCKING, NEXT_PUBLIC_APP_URL, NEXT_PUBLIC_MOCK_API_PORT as needed) and restart.","Use the `- KEY: reason` lines in the thrown message to fix exactly the failing keys.","For deployments: NEXT_PUBLIC_* vars must be present at build time — add them to your host's build environment, not just runtime.","Loosen the schema (optional().default(...)) for variables that are legitimately absent in some environments."],"exampleFix":"# before\n# apps/nextjs-pages/.env.local\n# (empty)\n\n# after\nAPI_URL=http://localhost:3000\nNEXT_PUBLIC_API_URL=http://localhost:3000\nNEXT_PUBLIC_ENABLE_API_MOCKING=false","handlingStrategy":"validation","validationCode":"// Prebuild script (scripts/check-env.ts) run before `next build`\nconst required = ['API_URL'];\nconst missing = required.filter((k) => !process.env[k]);\nif (missing.length) {\n  console.error(`Missing: ${missing.join(', ')}`);\n  process.exit(1);\n}","typeGuard":"import { z } from 'zod';\nconst EnvSchema = z.object({\n  API_URL: z.string(),\n  ENABLE_API_MOCKING: z.enum(['true', 'false']).optional(),\n});\nexport const isEnv = (o: unknown): o is z.infer<typeof EnvSchema> =>\n  EnvSchema.safeParse(o).success;","tryCatchPattern":"try {\n  const { env } = await import('@/config/env');\n} catch (e) {\n  console.error((e as Error).message);\n  process.exit(1);\n}","preventionTips":["Maintain per-app .env.local files — each app under apps/ has its own config root.","Remember NEXT_PUBLIC_* vars are inlined at build time: set them in the build environment, not just runtime.","Add an env check script to the prebuild phase in package.json.","Use z.enum(['true','false']) for boolean-ish flags to get clearer errors than the refine() string."],"tags":["environment-variables","zod","validation","nextjs-pages","startup"],"backgroundTag":"missing-env-var","analyzedSha":"9506629ed003a561c6627735480cce4994244bb4","analyzedAt":"2026-08-27T06:11:26.302Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}