« Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: undefined. » Ce message apparaît dans la console du navigateur, remplace l’aperçu du bloc concerné par un écran d’erreur générique dans l’éditeur, et ne désigne jamais nommément le composant fautif. Il indique simplement que React a tenté de rendre quelque chose qui vaut undefined là où il attendait un composant valide.
Ce guide détaille les trois causes les plus fréquentes de cette erreur dans un bloc Gutenberg, la méthode pour identifier laquelle s’applique, et le correctif associé à chacune.
Symptôme : ce que l’on observe exactement
L’éditeur affiche, à la place du bloc, un message « Ce bloc a rencontré une erreur et ne peut pas être affiché » (généré par le composant interne BlockErrorBoundary), tandis que la console du navigateur détaille l’erreur React sous-jacente. La pile d’appels (component stack) qui accompagne le message reste l’indice le plus utile : elle liste les composants parents jusqu’à celui qui a tenté de rendre l’élément invalide.
Diagnostic 1 : un export oublié après un renommage
La cause la plus fréquente survient après le renommage d’un fichier de composant, quand l’import correspondant n’a pas été mis à jour partout :
// PanneauReglages.js renommé en PanneauOptions.js
// mais l'import n'a pas été corrigé ailleurs :
import PanneauReglages from './PanneauReglages'; // fichier introuvable, import undefined
function Edit() {
return <PanneauReglages />; // undefined ici
}
Le correctif consiste à vérifier, dans l’onglet réseau ou dans le journal de compilation de wp-scripts, si un avertissement de module introuvable a été émis avant l’erreur React elle-même. Un simple grep du nom de fichier renommé dans l’ensemble du dossier src du bloc suffit généralement à retrouver l’import fautif.
Diagnostic 2 : confusion entre export nommé et export par défaut
La deuxième cause fréquente vient d’une incohérence entre la façon dont un composant est exporté et la façon dont il est importé :
// export nommé
export function PanneauOptions() { /* ... */ }
// import erroné, attend un export par défaut
import PanneauOptions from './PanneauOptions'; // undefined
// import correct pour un export nommé
import { PanneauOptions } from './PanneauOptions';
Ce type d’erreur passe souvent inaperçu à la relecture, car la syntaxe des deux imports se ressemble fortement. Un examen attentif de la ligne export dans le fichier source reste le moyen le plus rapide de trancher.
Diagnostic 3 : une dépendance de paquet mal résolue
Une troisième cause, moins fréquente mais plus difficile à repérer, survient quand deux versions différentes d’un même paquet WordPress (par exemple @wordpress/components) coexistent dans l’arborescence node_modules, souvent après l’ajout d’une nouvelle dépendance. Le bloc importe alors un composant depuis une version du paquet qui ne l’exporte pas encore ou plus :
npm ls @wordpress/components
# révèle parfois deux versions imbriquées à des profondeurs différentes
Le correctif passe généralement par la déclaration explicite du paquet en peerDependency, ou par un nettoyage du dossier node_modules suivi d’une réinstallation propre des dépendances.
Méthode de diagnostic rapide
- Lire la pile d’appels (
component stack) dans la console pour identifier le composant parent direct qui a tenté le rendu fautif. - Vérifier l’import du composant suspecté : chemin du fichier, export nommé ou par défaut.
- Si l’import semble correct, vérifier les versions installées du paquet concerné avec
npm ls. - En dernier recours, ajouter un
console.logjuste avant le rendu suspect pour confirmer que la variable vaut bienundefinedà cet endroit précis.
Prévenir la récidive
- Un outil de vérification de types comme TypeScript ou, à défaut, les commentaires JSDoc avec vérification activée, détecte ce genre d’import cassé avant l’exécution.
- Une règle ESLint sur les imports inutilisés ou introuvables (
import/no-unresolved) signale le problème dès l’écriture du code. - Documenter dans le fichier concerné si un export est nommé ou par défaut évite l’erreur de syntaxe la plus fréquente.
Sur nos projets, la première question posée face à ce message reste toujours la même : « qu’est-ce qui a été renommé récemment ? » Neuf fois sur dix, la réponse pointe directement vers le fichier fautif.
En résumé
« Element type is invalid » n’est jamais une erreur de logique métier : c’est toujours un problème d’import ou d’export mal aligné. La pile d’appels affichée dans la console reste la première chose à consulter, avant de suspecter un bug plus profond dans le bloc lui-même.
