Next.js : dépannage

Procédure de diagnostic

node --version
npm ls next react react-dom
rm -rf .next
npm run build 2>&1 | tail -40
npm run lint
npx tsc --noEmit

Supprimer .next/ règle de nombreux comportements étranges (cache de développement périmé). Lire le premier message d’erreur : les suivants en découlent souvent.

Erreurs de rendu

Message	Cause et solution
`Hydration failed because the server rendered HTML didn't match the client`	Rendu serveur et client différents (date, `Math.random`, `window`, extension de navigateur) : déplacer dans `useEffect`, ou `suppressHydrationWarning` pour un cas ciblé
`You're importing a component that needs useState. It only works in a Client Component`	Ajouter `'use client'` en tête du fichier
`window is not defined` / `document is not defined`	Code navigateur exécuté côté serveur : `'use client'` + `useEffect`, ou import dynamique sans rendu serveur
`Functions cannot be passed directly to Client Components`	Passer une Server Action ou définir la fonction côté client
`Only plain objects can be passed to Client Components from Server Components`	Donnée non sérialisable
`Error: Cookies can only be modified in a Server Action or Route Handler`	Écriture de cookie depuis un composant serveur
`Text content does not match server-rendered HTML`	Même cause que l’hydratation

Erreurs liées aux versions récentes

Symptôme	Cause et solution
`params.slug` renvoie `undefined` ou un avertissement `params should be awaited`	Depuis Next.js 15, `params`, `searchParams`, `cookies()` et `headers()` sont asynchrones : `await`
Données non rafraîchies, ou au contraire jamais mises en cache	La politique de cache de `fetch` a changé selon les versions : la déclarer (`cache`, `next.revalidate`)
`middleware` signalé comme obsolète	Les versions récentes le renomment `proxy` : lire le guide de mise à jour
`next lint` introuvable	Utiliser directement `eslint` selon la version

Avant une montée de version majeure : commit, branche dédiée, guide de migration officiel, codemods :

npx @next/codemod@canary upgrade latest
npm run build

Build

Message	Cause et solution
`Type error: …`	Erreur TypeScript : `npx tsc --noEmit` pour la liste complète
`ESLint: …`	Corriger ou assouplir la règle ; `npm run lint`
`Dynamic server usage: Route … couldn't be rendered statically because it used cookies`	Page statique qui lit `cookies()`/`headers()` : `export const dynamic = 'force-dynamic'`
`ECONNREFUSED` pendant `next build`	Appel à une base ou une API au moment de la construction : rendre la route dynamique
`JavaScript heap out of memory`	`NODE_OPTIONS=--max-old-space-size=4096 npm run build`
`Module not found: Can't resolve '…'`	Dépendance absente ou casse du nom de fichier (Linux sensible à la casse)
`Error occurred prerendering page`	Erreur dans une page statique : l’en-tête indique la route

Exécution

Symptôme	Piste
`502 Bad Gateway` derrière le proxy	Service arrêté : `systemctl status`, `journalctl -u monapp -n 50`
Écoute sur toutes les interfaces	`HOSTNAME=127.0.0.1`
Images 400 `url parameter is not allowed`	`images.remotePatterns`
`sharp` manquant	`npm install sharp`, même architecture que le serveur
Mémoire qui grossit	Cache d’images, connexions de base ouvertes à chaque requête : mutualiser le pool
Lenteur au premier accès	Page dynamique, optimisation d’image à la demande : mesurer avec l’onglet Réseau

Variables d’environnement

Symptôme	Piste
Variable vide dans le navigateur	Préfixe `NEXT_PUBLIC_` ; valeur figée au build
Variable vide sur le serveur	`.env.local` absent en production : utiliser l’environnement du service (`EnvironmentFile`)
Valeur obsolète après modification	Reconstruire (`NEXT_PUBLIC_*`) ou redémarrer le service

Développement

npm run dev -- --turbopack      # selon la version, Turbopack est déjà activé par défaut
rm -rf .next && npm run dev

Rechargement à chaud inactif sur serveur distant : tunnel SSH et --hostname 127.0.0.1.
Comportement différent entre dev et production : tester avec npm run build && npm run start.
Pages qui se rendent deux fois en développement : reactStrictMode.

Obtenir de l’aide

Lire le message jusqu’au bout (Next.js indique souvent le lien de documentation et la correction).
Reproduire dans un projet minimal.
Indiquer les versions (npm ls next react node) dans toute demande d’aide.

Ubuntu 24.04 et 26.04 : différences à connaître

Aucune propre à Next.js. Sous Linux, la casse des noms de fichiers compte, et la version de Node.js doit être celle exigée par la version de Next.js.

Pour aller plus loin

Guides de mise à jour, Guides thématiques
Retour : Installation