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

> Gutenberg affiche « Le bloc contient du contenu invalide ou inattendu » ? Récupérez le bloc sans rien perdre et traitez la cause : guide pas à pas.

- Auteur : WordPress Développement
- Publié le : 2026-10-02
- Mis à jour le : 2026-10-02
- URL : https://www.wpmoderne.fr/erreurs-wordpress/bloc-contenu-inattendu/

> Le HTML enregistré du bloc ne correspond plus à ce que son code produirait. Cliquez sur « Tentative de récupération », ou sur « Résoudre » puis « Convertir en HTML » pour conserver le contenu, et cherchez ce qui a modifié le bloc.

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](https://www.wpmoderne.fr/erreurs-wordpress/reponse-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é](https://www.wpmoderne.fr/erreurs-wordpress/type-fichier-non-autorise/), 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](https://www.wpmoderne.fr/blocs/notion-validation-migration-recuperation-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](https://www.wpmoderne.fr/blocs/tableau-deprecated-bloc-migrer-sans-casser-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](https://www.wpmoderne.fr/ia-mcp/generer-patterns-blocs-ia-valider-markup/).

## FAQ