Bloc : « contient du contenu invalide ou inattendu » (Gutenberg)

Le bloc contient du contenu invalide ou inattendu.

En anglais : Block contains unexpected or invalid content.

En ouvrant un article ou une page dans l’éditeur de blocs, un ou plusieurs blocs s’affichent dans un cadre d’avertissement : « Le bloc contient du contenu invalide ou inattendu. », accompagné des boutons « Tentative de récupération », « Résoudre » et « Convertir en HTML ». Le texte reste visible dans le cadre, mais le bloc n’est plus modifiable normalement. L’avertissement n’apparaît que dans l’éditeur : sur le site, le contenu enregistré continue de s’afficher tel quel.

Cette alerte est un garde-fou, pas une panne : l’éditeur refuse de réécrire silencieusement un contenu qu’il ne reconnaît plus, pour éviter de perdre des données. Elle apparaît après une modification manuelle du contenu, une mise à jour d’extension ou de thème, une migration ou un copier-coller depuis une source externe. Ne la confondez pas avec « La publication a échoué. La réponse n’est pas une réponse JSON valide », qui survient à l’enregistrement et fait l’objet de la fiche réponse JSON invalide.

Ce que signifie cette erreur

Un article Gutenberg est stocké sous forme de HTML entouré de commentaires (<!-- wp:paragraph -->…), dans la colonne post_content de la table wp_posts. À l’ouverture, l’éditeur analyse ce texte et, pour chaque bloc, compare le HTML enregistré (le « contenu d’origine ») au HTML que la fonction save du bloc produirait avec ses attributs actuels. Cette validation est réalisée par le paquet JavaScript blocks (wp-includes/js/dist/blocks.js). Si les deux HTML ne sont pas équivalents, le bloc est marqué invalide et l’éditeur affiche l’avertissement (wp-includes/js/dist/block-editor.js).

La console du navigateur (touche F12, onglet « Console ») explique alors la différence, avec des messages comme « Block validation failed for `core/paragraph` » suivis du contenu généré par save et du contenu lu dans l’article, ou des lignes plus fines : « Expected token of type… », « Expected attribute… of value… », « Encountered unexpected attribute… ». Ces messages ne sont affichés qu’en anglais. Ils indiquent précisément quelle balise ou quel attribut diffère.

Les trois boutons correspondent à trois comportements. « Tentative de récupération » recrée le bloc à partir de ses attributs avec le save actuel ; le HTML qui ne peut pas être relu est perdu. « Résoudre » ouvre une fenêtre « Résoudre les problèmes de ce bloc » qui compare le contenu « Actuel » à l’état « Après conversion », et propose de conserver l’original en HTML ou de le convertir en blocs. « Convertir en HTML » place l’intégralité du contenu d’origine dans un bloc « HTML personnalisé », sans rien perdre. Aucun changement n’est enregistré tant que vous n’avez pas cliqué sur « Mettre à jour » ou « Enregistrer ».

Diagnostic rapide

Symptôme / constat	Cause probable	À vérifier
Un seul bloc concerné, après une modification manuelle du code	HTML ou commentaire de bloc altéré à la main	Éditeur de code, balises et attributs du bloc
Un type de bloc invalide dans de nombreux articles après une mise à jour	Le save du bloc a changé sans entrée deprecated	Version de l’extension ou du thème fournissant le bloc
Blocs invalides après une migration ou un « chercher-remplacer » en base	Attributs JSON ou URL modifiés dans les commentaires de blocs	Requête sur post_content, sauvegarde de la base
Blocs invalides pour les contenus créés par un auteur ou un contributeur	Balises ou attributs retirés à l’enregistrement faute de la capacité unfiltered_html	Rôle de l’utilisateur, extension de sécurité
Blocs invalides après un collage de contenu généré par un outil externe	Balisage de bloc incomplet ou incohérent	Console du navigateur, messages « Block validation »

Les causes les plus fréquentes

1. Une extension ou un thème a modifié le rendu (save) d’un bloc sans prévoir de migration pour les anciens contenus.
2. Une modification directe du HTML dans l’éditeur de code ou en base de données, qui a cassé un commentaire de bloc ou ses attributs JSON.
3. Un remplacement en masse (changement d’URL, de domaine, de classe CSS) mal maîtrisé après une migration.
4. Une version différente d’extension entre deux environnements (préproduction et production, sauvegarde restaurée).
5. Un filtrage du contenu à l’enregistrement (wp_filter_post_kses, pour les rôles sans la capacité unfiltered_html décrite dans la fiche type de fichier non autorisé, ou une extension de sécurité) qui supprime des attributs.
6. Un contenu rédigé ou généré en dehors de l’éditeur, avec un balisage de bloc approximatif.

Solutions pas à pas

1. Sauvegarder avant toute manipulation

Avant de corriger, conservez une copie de l’article : bouton « Révisions » dans la barre latérale pour revenir à une version saine, ou export de la base de données avant toute opération en masse. Vous éviterez de perdre du texte si une conversion donne un résultat inattendu.

2. Utiliser « Tentative de récupération »

Pour un bloc simple (paragraphe, titre, image), cliquez sur le bouton « Tentative de récupération ». L’éditeur reconstruit le bloc avec son rendu actuel. Vérifiez visuellement le résultat, puis enregistrez. Si quelque chose manque, annulez avec Ctrl+Z (Cmd+Z sur Mac) et passez à l’étape suivante.

3. Comparer avec « Résoudre »

Cliquez sur « Résoudre » : la fenêtre compare le contenu actuel et celui obtenu après conversion, les différences étant surlignées. Choisissez « Convertir en HTML » pour garder exactement le contenu d’origine, ou « Convertir en blocs » pour laisser WordPress retransformer le HTML en blocs standards. Le second choix convient bien à un contenu texte ; le premier protège un balisage spécifique.

4. Convertir en HTML pour conserver l’existant

Quand le contenu compte plus que son éditabilité (mise en page particulière, code intégré), le bouton « Convertir en HTML » crée un bloc « HTML personnalisé » contenant le balisage tel quel. Vous perdez l’édition visuelle du bloc, mais rien d’autre. C’est le meilleur choix en urgence.

5. Inspecter le code du bloc

Ouvrez le menu « Options » (trois points en haut à droite), puis « Éditeur de code ». Repérez le commentaire du bloc (<!-- wp:nom/bloc {"attribut":"valeur"} -->) : un guillemet manquant, une accolade ou une balise de fermeture absente suffit à invalider un bloc. Corrigez, puis quittez l’éditeur de code. Vous pouvez aussi extraire le contenu en WP-CLI pour l’examiner (lecture seule) :

wp post get 123 --field=post_content > article-123.html

Une fois corrigé dans un éditeur de texte, vous pouvez le réinjecter avec wp post update 123 article-123.html, uniquement après sauvegarde de la base, car cette commande remplace le contenu de l’article.

6. Traiter la cause plutôt que le symptôme

Si plusieurs articles sont concernés, ne les réparez pas un par un. Vérifiez la version de l’extension ou du thème qui fournit le bloc et comparez-la à celle de l’environnement où le contenu a été créé : revenir à la version précédente restaure souvent la validité des blocs. Avec WP-CLI, l’installation d’une version précise s’écrit :

wp plugin list --fields=name,version,status
wp plugin install nom-de-l-extension --version=1.2.3 --force

Pour un remplacement en masse suspecté, restaurez la sauvegarde de la base et refaites l’opération en visant les attributs précis. Notre article sur la différence entre validation, migration et récupération des blocs aide à identifier le mécanisme en cause.

7. Côté développeur : déclarer une dépréciation

Si vous maintenez le bloc, ne modifiez jamais le save sans conserver l’ancienne version dans le tableau deprecated : l’éditeur essaiera chaque version et migrera le contenu en silence. Exemple minimal en JavaScript :

registerBlockType( 'mon-plugin/carte', {
	// ... edit, attributes, save (nouvelle version)
	deprecated: [
		{
			attributes: { titre: { type: 'string' } },
			save( { attributes } ) {
				// Ancien rendu, à l’identique de la version précédente.
				return <h3>{ attributes.titre }</h3>;
			},
			migrate( attributes ) {
				return { ...attributes, niveau: 3 };
			},
		},
	],
} );

La démarche complète est décrite dans le tableau deprecated pour migrer un bloc sans casser le contenu. Pour un bloc dynamique rendu en PHP, dont la fonction save renvoie null, ce problème ne se pose pas de la même façon.

Prévenir l’erreur

• Ne modifiez pas à la main le HTML des blocs en base ; passez par l’éditeur ou par des commandes testées sur une copie.
• Testez les mises à jour d’extensions de blocs en préproduction sur des contenus existants, pas seulement sur des pages neuves.
• Ajoutez systématiquement une entrée deprecated à chaque changement de save.
• Faites un chercher-remplacer en base uniquement avec un outil qui gère le JSON et les données sérialisées, après sauvegarde.
• Validez le balisage des blocs générés automatiquement avant de les insérer en base, comme le montre notre article sur la génération de patterns de blocs par IA.

FAQ