# So beheben Sie, dass KI die Validierung von Umgebungsvariablen vergisst

> KI-Agenten lesen process.env-Werte direkt ohne Validierung, was zu stillen undefined-Fehlern und fehlenden Startfehlern führt, wenn Umgebungsvariablen fehlen.

**Type:** Failure  
**Tools:** Cursor, Claude Code, Codex, Windsurf  
**Stack:** Next.js, TypeScript, Cloudflare  
**Updated:** 2026-06-08

---

Der Agent greift direkt auf `process.env.SOME_KEY` zu. Wenn die Variable fehlt, startet die App still und heimlich kaputt — kein Absturz, keine Warnung, nur `undefined`, das durch die Geschäftslogik fließt.

## Das Symptom

Rohe `process.env`-Zugriffe sind über die gesamte Codebasis verstreut, ohne Schema, ohne Typsicherheit und ohne Startbehauptung.

```ts
// lib/stripe.ts — WRONG
import Stripe from "stripe";

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
  apiVersion: "2024-06-20",
});
// If STRIPE_SECRET_KEY is undefined, Stripe SDK accepts it and every
// charge silently fails at runtime instead of at startup.
```

## Warum es passiert

Der Agent optimiert auf Kürze und schnelles Erreichen funktionierenden Codes. Die Validierung von Umgebungsvariablen ist Boilerplate, die in den meisten Trainingsbeispielen nicht vorkommt, daher überspringt das Modell sie und geht direkt zur Integration.

## Wie man es erkennt

- `process.env.FOO` wird ohne Nicht-Null-Assertion oder Fallback-Prüfung verwendet.
- Keine `env.ts` / `env.mjs`-Validierungsdatei im Projekt.
- Der TypeScript-Typ eines Umgebungswerts ist an der Aufrufstelle `string | undefined`.
- App startet ohne Fehler, selbst wenn `.env.local` leer ist.

## Wie man es behebt

Validieren Sie alle erforderlichen Umgebungsvariablen beim Start mit einem Zod-Schema, sodass der Prozess mit einer klaren Meldung abstürzt, bevor er eine einzige Anfrage bedient.

```ts
// lib/env.ts — CORRECT
import { z } from "zod";

const envSchema = z.object({
  STRIPE_SECRET_KEY: z.string().min(1),
  DATABASE_URL: z.string().url(),
  NEXTAUTH_SECRET: z.string().min(32),
  NODE_ENV: z.enum(["development", "production", "test"]).default("development"),
});

export const env = envSchema.parse(process.env);
//                             ^^^^^ throws at startup if any var is missing
```

```ts
// lib/stripe.ts — CORRECT (import validated env)
import Stripe from "stripe";
import { env } from "@/lib/env";

export const stripe = new Stripe(env.STRIPE_SECRET_KEY, {
  apiVersion: "2024-06-20",
});
```

```txt
[ ] Create lib/env.ts with a Zod schema covering every required variable
[ ] Import env from lib/env everywhere — never use process.env directly
[ ] Add lib/env.ts to the module graph so it runs at server startup (import in next.config.ts)
[ ] Document all variables in .env.example with placeholder values
[ ] Use z.string().url() / z.string().min(n) for format constraints, not just presence
```

## Fix-Prompt

```txt title="Fix Prompt"
Every raw process.env access in this file is unvalidated. Create a lib/env.ts
module that parses and validates all required environment variables with Zod at
startup. Replace every process.env.FOO reference in the codebase with the
typed env.FOO import. Add a .env.example file listing every variable with a
placeholder value and comment.
```

## Test

```bash
# Find any remaining raw process.env reads outside of lib/env.ts
grep -rn "process\.env\." --include="*.ts" --include="*.tsx" . \
  | grep -v "lib/env.ts" \
  | grep -v "next.config" \
  | grep -v "node_modules" \
  && echo "FAIL: raw process.env reads found" || echo "OK"
```