« Failed to load block: aucun bloc trouvé » — ce message, ou son absence totale et plus trompeuse encore, un simple silence dans l’inserteur, accompagne un problème classique : un bloc déclaré côté PHP qui n’apparaît jamais dans la liste des blocs disponibles, sans qu’aucune erreur explicite n’oriente le diagnostic. Ce billet ne traite pas des cascade layers CSS, sans rapport avec ce symptôme précis.
Le scénario habituel concerne une extension qui enregistre un bloc via register_block_type(), avec un chemin correct vers le dossier contenant block.json, mais dont le bloc reste introuvable dans l’éditeur, ou pire, provoque une erreur PHP silencieuse dans les journaux du serveur.
Symptôme : un enregistrement qui semble correct mais ne produit rien
Le code d’enregistrement, à première vue, ne contient aucune faute évidente :
register_block_type( __DIR__ . '/build/mon-bloc' );Pourtant, le bloc n’apparaît pas dans l’inserteur, et l’éditeur ne signale rien de particulier. Le contenu déjà publié avec ce bloc, s’il en existe, s’affiche comme un bloc non reconnu.
Diagnostic : où et quand cet appel est exécuté
La cause la plus fréquente tient à l’emplacement de cet appel dans le cycle de chargement de WordPress. register_block_type() doit être appelé après l’action init, jamais avant, car plusieurs mécanismes internes nécessaires à l’enregistrement d’un bloc, notamment le chargement des traductions et l’initialisation du registre de blocs, ne sont pas encore prêts plus tôt dans le cycle de chargement.
// Incorrect : exécuté au chargement du fichier, avant l'action init
register_block_type( __DIR__ . '/build/mon-bloc' );
// Correct : exécuté sur l'action init
add_action( 'init', function () {
register_block_type( __DIR__ . '/build/mon-bloc' );
} );
Un second piège : l’ordre entre plusieurs actions init
Même correctement accroché à init, un bloc peut encore échouer à apparaître si sa catégorie personnalisée, déclarée via le filtre block_categories_all, s’exécute après l’enregistrement du bloc lui-même plutôt qu’avant. Si le bloc référence une catégorie qui n’existe pas encore au moment de son enregistrement, WordPress l’assigne silencieusement à la catégorie par défaut, ou dans certains cas le bloc reste simplement invisible dans une interface qui filtre par catégorie.
// Doit s'exécuter avant l'enregistrement du bloc qui l'utilise
add_filter( 'block_categories_all', function ( $categories ) {
$categories[] = array(
'slug' => 'monplugin',
'title' => 'Mon extension',
);
return $categories;
} );
add_action( 'init', function () {
register_block_type( __DIR__ . '/build/mon-bloc' );
}, 20 );Ici, la priorité 20 passée à add_action garantit que l’enregistrement du bloc intervient après le filtre de catégorie, appelé lui à la priorité par défaut de 10.
Vérifier le registre effectif
Pour confirmer qu’un bloc est réellement enregistré, la commande WP-CLI suivante liste tous les blocs connus du registre :
$ wp eval 'foreach ( array_keys( WP_Block_Type_Registry::get_instance()->get_all_registered() ) as $nom ) { echo $nom . PHP_EOL; }'Si le nom du bloc concerné n’apparaît pas dans cette liste, l’enregistrement a échoué avant même d’atteindre l’éditeur, ce qui confirme un problème d’ordre de chargement plutôt qu’un problème côté JavaScript.
Correctif et prévention
La correction tient en deux règles simples à respecter systématiquement : accrocher tout appel à register_block_type() sur l’action init, et choisir une priorité explicite lorsque le bloc dépend d’une catégorie ou d’un autre élément également enregistré sur ce même hook.
- Ne jamais appeler
register_block_type()directement au chargement du fichier PHP. - Vérifier l’ordre relatif des priorités quand plusieurs éléments dépendants s’accrochent au même hook
init. - Contrôler le registre effectif via WP-CLI plutôt que de se fier uniquement à l’absence de message d’erreur.
En résumé
Un bloc invisible dans l’inserteur, sans message d’erreur clair, pointe presque toujours vers un problème d’ordre de chargement : un enregistrement exécuté trop tôt, avant l’action init, ou une dépendance, comme une catégorie personnalisée, déclarée après le bloc qui en a besoin. Vérifier le registre effectif via WP-CLI reste le moyen le plus rapide de confirmer cette hypothèse avant de chercher plus loin.
