Block Contains Unexpected or Invalid Content: Fix It

When a block contains unexpected or invalid content, the editor is telling you one specific thing: the HTML stored in post_content no longer matches what that block’s save() function produces today. Nothing is corrupt, nothing is lost, and the fix is usually three clicks — but which three clicks depends on why the two stopped matching, and the warning itself does not tell you that.

The block editor re-runs every block’s save function when it loads a post, then compares the result against the markup already in the database. A mismatch of a single attribute, a changed wrapper tag, or an apostrophe stored as ' instead of ' is enough to fail the comparison. That is why this warning appears on posts you have not touched in a year: something else changed — a plugin update, a theme switch, a sanitiser rewriting your markup on save.

Why a block contains unexpected or invalid content

Static blocks store their own output. When you save a paragraph, the editor serialises it to HTML wrapped in block comments and writes the whole thing into post_content:

<!-- wp:paragraph {"align":"center"} -->
<p class="has-text-align-center">Hello.</p>
<!-- /wp:paragraph -->

The comment carries the attributes. The HTML between the comments is a cached copy of what save() returned at the moment you pressed Update. On the next load, the editor parses the attributes out of the comment, feeds them back through the block’s current save function, and checks whether it gets the same HTML. If it does, the block is valid. If it does not, you get the warning.

That comparison is done in JavaScript, in your browser, and it logs its reasoning. Open the console on the affected post and you will see something close to this:

Block validation: Block validation failed for `core/html`.

Expected:
<p>Terms &amp; conditions apply</p>

Actual:
<p>Terms & conditions apply</p>

Expected is what the current save function wants. Actual is what is in the database. In that example the whole problem is one ampersand that was stored raw and is now being escaped — harmless, and recovery will fix it cleanly. The console is the only place that tells you which it is, which is why reading it first is not optional.

Dynamic blocks — the ones registered with a PHP render_callback and no save() output — cannot fail this way. They store nothing but the comment, so there is nothing to compare. That asymmetry matters later when we get to prevention.

Three warnings that look the same and are not

Half the time people spend on this error is spent fixing the wrong problem, because the editor has three different failure notices and they get described interchangeably in support threads. Check which one you actually have before doing anything.

What actually breaks the match

In rough order of how often I find each one on client sites:

If you cannot tell which of these it is, the ordinary isolation method works: deactivate plugins in halves and reload the post, watching whether the warning survives. Troubleshooting a WordPress plugin conflict step by step covers doing that without taking a live site down. Switching temporarily to a default block theme answers the theme.json question in the same way.

Fixing one block without losing the content

Four routes, in the order I would try them. None of them writes to the database until you click Update, so you can explore freely and leave without saving.

1. Attempt Block Recovery

The button on the warning itself. It discards the stored HTML and regenerates it from the attributes in the block comment. When the attributes are complete — which they are for a cosmetic entity or class-name mismatch — this is exactly right and the result is identical to what you had.

It is the wrong choice when the content lives in the HTML rather than in the attributes, and the attributes are incomplete. The classic failure is a heading that somehow ended up containing a nested paragraph: recovery regenerates the heading from its attributes and the nested content simply is not in them, so you get an empty heading. Read the console first and you will know which case you are in before you click.

2. Resolve, and read the diff

In the block’s ellipsis menu, Resolve opens a side-by-side comparison of the stored markup and what the editor would write, with removed content highlighted. It is the console output in a nicer frame, and it ends in the same two choices: Convert to Blocks to accept the regenerated version, or Convert to HTML to keep the raw markup as-is.

Use this when the console told you something was being dropped and you want to see exactly what before deciding.

3. Convert to HTML

Turns the block into a Custom HTML block containing the stored markup verbatim. Nothing is lost and the front end renders identically — but you have traded a real block for an opaque lump of HTML. It will not pick up theme styling changes, colour palette updates, or responsive settings, and the next person to edit the page gets a code box instead of a text field.

Treat it as a holding position for content you cannot afford to regenerate: convert, publish, then rebuild the block properly when you have time. It is also the honest answer for one-off hand-written markup that was never really a block in the first place.

4. Roll back to a revision

Worth remembering that the error is about stored content, so an earlier copy of that content is a legitimate fix — particularly when the damage was done by a search-replace or a sanitiser rather than by a code change. Restoring an earlier version of a post using revisions walks through comparing and restoring one.

Two caveats. Restoring brings back the markup that matched the old save function, so if the cause was a plugin update, the restored version will fail validation too. And revisions are capped — check WP_POST_REVISIONS in wp-config.php before you count on there being enough history.

When it hit every post at once

There is no WP-CLI command that finds invalid blocks, and there cannot be a straightforward one: validation means running the block’s JavaScript save function and diffing the output, so the answer only exists inside a loaded editor. Anything claiming to scan for broken blocks server-side is pattern-matching markup, not validating it.

What you can do from the shell is build the list of posts that use the suspect block, so you know the size of the job:

# Posts and pages containing a given block type
wp db query "SELECT ID, post_type, post_title FROM wp_posts
  WHERE post_content LIKE '%wp:acme/slider%'
  AND post_status IN ('publish','draft','pending','private')
  ORDER BY post_modified DESC" --skip-column-names

# Just the count, to decide between fixing by hand and asking the vendor
wp db query "SELECT COUNT(*) FROM wp_posts
  WHERE post_content LIKE '%wp:acme/slider%'" --skip-column-names

Substitute your table prefix and the real block name — you will find it in the block comment, or in the console line that named the failing block type. If that count is in the hundreds, stop and contact the plugin author before you start clicking: a missing deprecation is their bug, and a point release that adds one fixes every post at once with no edits from you.

For a few dozen posts, recovering block by block is tedious enough to be worth automating in the browser. Open the post in the editor, open the console, and run this against the loaded editor state. It uses the same documented store actions the recovery button uses, and recovers nested blocks too:

( function () {
  const store = 'core/block-editor';
  const { select, dispatch } = wp.data;
  const { createBlock } = wp.blocks;
  let fixed = 0;

  function walk( rootClientId ) {
    select( store ).getBlocks( rootClientId ).forEach( function ( block ) {
      if ( ! select( store ).isBlockValid( block.clientId ) ) {
        dispatch( store ).replaceBlock(
          block.clientId,
          createBlock( block.name, block.attributes, block.innerBlocks )
        );
        fixed += 1;
        return;
      }
      if ( block.innerBlocks.length ) {
        walk( block.clientId );
      }
    } );
  }

  walk();
  console.log( 'Recovered ' + fixed + ' block(s). Nothing is saved until you press Update.' );
} )();

Synced patterns and template parts

A synced pattern stores its blocks once, in a wp_block post, and every page that uses it renders from that single copy. So one invalid block inside a synced pattern shows up as invalid everywhere the pattern appears — and recovering it on a page does nothing lasting, because the page is not where the markup lives. Edit the pattern itself from the Patterns screen, recover it there, save, and all its uses come good at once.

Template parts in a block theme behave the same way: the header or footer is a separate entity, edited in the Site Editor, not in the post you were looking at. If the warning is in a region you cannot select in the post editor, that is why. Which container a given chunk of markup belongs in is its own decision, and it changes how far a single broken block can spread — synced patterns vs template parts works through that choice, including why an unsynced pattern confines the damage to one page while a synced one does not. Customising a block theme with theme.json or a child theme covers which parts of a block theme live where, which is also the quickest way to work out whether a theme.json change caused the mismatch in the first place.

If you build the block: write the deprecation

Every time you change what a block’s save() emits, you break the stored copies in your users’ databases unless you tell the editor how to read the old shape. That is what the deprecated array is for: a list of previous versions, each with its own attributes, supports and save, tried in turn when the current save function fails to match.

// v1 wrapped the text in a p; the current save uses a div.
const v1 = {
  attributes: {
    content: { type: 'string', source: 'html', selector: 'p' },
  },
  save( { attributes } ) {
    return createElement( 'p', null, attributes.content );
  },
};

registerBlockType( 'acme/notice', {
  // ...current attributes and edit...
  save( { attributes } ) {
    return createElement( 'div', null, attributes.content );
  },
  deprecated: [ v1 ],
} );

Three details from the API docs that catch people out. Deprecations do not chain like database migrations — each entry is matched independently against the original stored content, so a new migrate may need adding to several entries rather than just the newest. A deprecation whose save does not match is skipped entirely, including its migrate. And attributes, supports and save are not inherited from the current block, so each entry has to spell them out in full. List them newest-first so the likeliest match is tried first.

The alternative is to not store markup at all. A block registered with a PHP render_callback and no save output cannot fail validation, because there is nothing cached to compare. You give up the ability to edit the output as HTML and you render on every request instead of serving stored markup, so it is a real trade-off rather than a free win — but for anything whose output depends on site state, it is the right shape.

There is a lighter version of that same idea worth knowing before you build a block at all. If the only dynamic part is one value — a price, a date, a per-post link — the Block Bindings API lets a core Paragraph, Heading, Image or Button pull that value from a custom field at render time. The surrounding block is still a plain core block with ordinary stored markup, so you get server-resolved content without taking on a block’s deprecation burden.

Reducing how often this happens

One piece of context worth having: core contributors are actively unhappy with how often users see this warning. A proposal in the Gutenberg repository would replace today’s binary valid/invalid check with five graded validation levels, so blocks with recoverable differences would be regenerated quietly instead of flagged. It has not been merged, and the objections raised against it are about exactly the risk described above — silently rewriting content can lose things nobody meant to lose. Treat it as a direction of travel, not a fix that is coming next release.

Frequently asked questions

Sources

• Block Deprecation in the WordPress Block Editor Handbook — the deprecated array structure, how entries are matched, and the inheritance and ordering rules quoted above
• The core/block-editor data store reference — the signatures for getBlocks, isBlockValid and replaceBlock used in the console snippet
• Resolve block errors in WordPress — the Resolve dialog, the Convert to Blocks and Convert to HTML options, and the recovery flow
• Gutenberg issue 13668 — the console output format, and the entity and boolean-attribute mismatches that trip up Custom HTML blocks
• Gutenberg issue 45179 — pattern markup from a newer release failing validation on an older site
• Gutenberg pull request 73116 — the unmerged block validation levels proposal, including the content-loss objections raised against it