React : dépannage

Outils de diagnostic

Console du navigateur : première source d’information (erreurs, avertissements).
React DevTools (extension) : arbre des composants, props, état, profilage.
Onglet Réseau : requêtes, codes de statut, corps des réponses.
Terminal : messages de Vite ou du compilateur TypeScript.

node --version
npm ls react react-dom
npx tsc --noEmit            # erreurs de types
npm run lint
npm run build

Erreurs fréquentes

Message	Cause et solution
`Objects are not valid as a React child`	Un objet est affiché directement : afficher ses champs
`Each child in a list should have a unique "key" prop`	Ajouter `key` stable aux éléments de `map`
`Too many re-renders`	`set…` appelé pendant le rendu : le déplacer dans un événement ou un effet
`Rendered more hooks than during the previous render`	Hook appelé dans une condition ou après un `return`
`Invalid hook call`	Hook hors composant, ou deux copies de React (`npm ls react`)
`Cannot read properties of undefined (reading 'x')`	Donnée absente : vérifier chargement, `?.`
`X is not defined` / `X is not a function`	Import manquant ou export par défaut/nommé confondu
`Failed to resolve import "…"`	Chemin ou dépendance introuvable, casse du nom de fichier
`A component is changing an uncontrolled input to be controlled`	Valeur initiale `undefined` : utiliser `''`
`Warning: Can't perform a React state update on an unmounted component`	Nettoyer effets et requêtes
`Hydration failed`	Rendu serveur et rendu navigateur différents (voir Next.js)
`Uncaught Error: Minified React error #…`	Message complet : ouvrir le lien donné par React, ou lancer en développement

Boucles de rendu et effets

// Piège : l'objet est recréé à chaque rendu, l'effet se relance sans fin
const options = { page: 1 };
useEffect(() => {
  charger(options);
}, [options]);

// Correct : valeurs primitives en dépendances
useEffect(() => {
  charger({ page });
}, [page]);

Causes habituelles : objet ou fonction créés dans le rendu et placés dans les dépendances, effet qui met à jour l’une de ses propres dépendances. Le plugin ESLint react-hooks signale beaucoup de ces cas (règle exhaustive-deps).

`StrictMode`

En développement, StrictMode exécute deux fois les rendus et les effets : un effet qui fonctionne mal « deux fois » manque de nettoyage. Ce double appel ne se produit pas en production. Ne pas le désactiver pour masquer le problème.

TypeScript

Message	Piste
`Property 'x' does not exist on type …`	Type incomplet : compléter le type ou vérifier la donnée
`Type 'string \| undefined' is not assignable to type 'string'`	Valeur facultative : valeur par défaut ou test
`Object is possibly 'null'`	`useRef` initial `null` : `ref.current?.…`
`JSX element implicitly has type 'any'`	Types React manquants : `npm install -D @types/react @types/react-dom`

Build et déploiement

Symptôme	Piste
Fonctionne en `dev`, échoue en `build`	Erreur de types (`tsc`), import avec mauvaise casse (Linux sensible à la casse)
Page blanche en production	Console : chemin des assets (`base`), erreur d’exécution
404 en rechargeant une route	Repli sur `index.html` (voir Performance et déploiement)
`JavaScript heap out of memory`	`NODE_OPTIONS=--max-old-space-size=4096 npm run build`
Variables `VITE_*` absentes	Définies au moment du build, pas à l’exécution

Mettre à jour React

npm outdated react react-dom
npm install react@latest react-dom@latest
npm install -D @types/react@latest @types/react-dom@latest

Lire le guide de mise à jour de la version visée (react.dev/blog).
Mettre à jour les bibliothèques qui dépendent de React (routeur, composants UI) vers des versions compatibles.
Lancer les tests, npm run build, parcourir l’application.

Changements notables de React 19 : ref est une prop ordinaire (plus besoin de forwardRef pour les nouveaux composants), les actions de formulaire (useActionState), certaines API retirées. Un outil de migration automatique existe (npx codemod@latest react/19/migration-recipe).

Obtenir de l’aide

Reproduire le problème dans un exemple minimal.
Chercher le texte exact du message.
Vérifier les versions (npm ls react) et la compatibilité des bibliothèques.

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

Aucune propre à React. Sous Linux, vérifier la casse des noms de fichiers dans les imports.

Pour aller plus loin

Référence React, Erreurs minifiées
Retour : Installation