alan2207/bulletproof-react · critical · Error

Invalid env provided. The following variables are missing or

Error message

Invalid env provided.
The following variables are missing or invalid:
${Object.entries(parsedEnv.error.flatten().fieldErrors)
.map(([k, v]) => `- ${k}: ${v}`)
.join('\n')}

What it means

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).

Source

Thrown at apps/nextjs-app/src/config/env.ts:26

      .string()
      .refine((s) => s === 'true' || s === 'false')
      .transform((s) => s === 'true')
      .optional(),
    APP_URL: z.string().optional().default('http://localhost:3000'),
    APP_MOCK_API_PORT: z.string().optional().default('8080'),
  });

  const envVars = {
    API_URL: process.env.NEXT_PUBLIC_API_URL,
    ENABLE_API_MOCKING: process.env.NEXT_PUBLIC_ENABLE_API_MOCKING,
    APP_URL: process.env.NEXT_PUBLIC_URL,
    APP_MOCK_API_PORT: process.env.NEXT_PUBLIC_MOCK_API_PORT,
  };

  const parsedEnv = EnvSchema.safeParse(envVars);

  if (!parsedEnv.success) {
    throw new Error(
      `Invalid env provided.
  The following variables are missing or invalid:
  ${Object.entries(parsedEnv.error.flatten().fieldErrors)
    .map(([k, v]) => `- ${k}: ${v}`)
    .join('\n')}
  `,
    );
  }

  return parsedEnv.data ?? {};
};

export const env = createEnv();

View on GitHub (pinned to 9506629ed0)

Solutions

1. 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.
2. Check the error message body: each `- KEY: [reason]` line names the failing variable — fix exactly those keys in your environment/CI settings.
3. If deploying, add API_URL (and any other listed keys) to your hosting provider's environment variables and redeploy.
4. If a variable is genuinely optional in your setup, mark it optional/defaulted in EnvSchema (like APP_URL) instead of leaving it required.

Example fix

# before (.env.local missing or incomplete)
# App crashes: Invalid env provided.

# after
# apps/nextjs-app/.env.local
API_URL=http://localhost:3000
NEXT_PUBLIC_ENABLE_API_MOCKING=false
NEXT_PUBLIC_APP_URL=http://localhost:3000

// Run before importing app code that uses @/config/env
import { createEnv } from '@/config/env.schema'; // or inline the check
const required = ['API_URL'];
const missing = required.filter((k) => !process.env?.[k]);
if (missing.length) {
  console.error(`Missing env vars: ${missing.join(', ')}`);
  process.exit(1);
}

import { z } from 'zod';
const EnvSchema = z.object({
  API_URL: z.string().url(),
  ENABLE_API_MOCKING: z
    .string()
    .refine((s) => s === 'true' || s === 'false')
    .optional(),
});
const isEnv = (o: unknown): o is z.infer<typeof EnvSchema> =>
  EnvSchema.safeParse(o).success;

// Env is parsed at module load; catch at the entrypoint/bootstrap level
try {
  const { env } = await import('@/config/env');
} catch (e) {
  console.error((e as Error).message); // lists failing keys
  process.exit(1);
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Invalid env provided. The following variables are missing or
• Invalid env provided. The following variables are missing or

AI-assisted analysis of alan2207/bulletproof-react@9506629ed0 (2026-08-27). Data as JSON: /api/errors/5ca285d6177cc559. Report an issue: GitHub.