# Comment corriger l'oubli de validation des variables d'environnement par l'IA

> Les agents IA lisent les valeurs process.env directement sans validation, ce qui provoque des bugs silencieux d'undefined et des erreurs de démarrage manquantes lorsque les variables d'environnement sont absentes.

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

---

L'agent accède directement à `process.env.SOME_KEY`, donc lorsque la variable est absente, l'application démarre silencieusement cassée — pas de plantage, pas d'avertissement, juste `undefined` qui circule dans la logique métier.

## Le symptôme

Des lectures brutes de `process.env` dispersées dans la base de code sans schéma, sans sécurité de type et sans assertion au démarrage.

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

## Pourquoi cela se produit

L'agent optimise la brièveté et l'obtention rapide d'un code fonctionnel. La validation des variables d'environnement est un code passe-partout qui n'apparaît pas dans la plupart des exemples d'entraînement, donc le modèle l'ignore et va directement à l'intégration.

## Comment le repérer

- `process.env.FOO` utilisé sans assertion non-nulle ou vérification de repli.
- Aucun fichier de validation `env.ts` / `env.mjs` dans le projet.
- Le type TypeScript d'une valeur d'env est `string | undefined` au site d'appel.
- L'application démarre sans erreur même lorsque `.env.local` est vide.

## Comment le corriger

Validez toutes les variables d'env requises au démarrage à l'aide d'un schéma Zod afin que le processus plante avec un message clair avant de servir une seule requête.

```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
```

## Invite de correction

```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"
```