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

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

Source

Thrown at apps/react-vite/src/config/env.ts:28

      .optional(),
    APP_URL: z.string().optional().default('http://localhost:3000'),
    APP_MOCK_API_PORT: z.string().optional().default('8080'),
  });

  const envVars = Object.entries(import.meta.env).reduce<
    Record<string, string>
  >((acc, curr) => {
    const [key, value] = curr;
    if (key.startsWith('VITE_APP_')) {
      acc[key.replace('VITE_APP_', '')] = value;
    }
    return acc;
  }, {});

  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

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.

Example fix

# before
# apps/react-vite/.env.local
API_URL=http://localhost:3000   # wrong prefix → not exposed → error

# after
# apps/react-vite/.env.local
VITE_APP_API_URL=http://localhost:3000
VITE_APP_ENABLE_API_MOCKING=false

Defensive patterns

Strategy: validation

Validate before calling

// Fail with a clear message before the app boots
const needed = ['VITE_APP_API_URL'];
const missing = needed.filter((k) => !(k in import.meta.env));
if (missing.length) {
  throw new Error(`Missing VITE_APP_ vars: ${missing.join(', ')}`);
}

Type guard

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

Try / catch

// module-scope throw: catch where env is first consumed, e.g. main.tsx
try {
  const { env } = await import('@/config/env');
} catch (e) {
  document.body.innerHTML = `<pre>${(e as Error).message}</pre>`;
  throw e;
}

Prevention

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.

When it happens

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

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

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

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