If your ACF blocks are in the sidebar after updating to WordPress 7.1, nothing in your theme broke and nothing in ACF broke. ACF blocks in the sidebar is a symptom of a change in WordPress core, not of anything you shipped. WordPress 7.1 made the block editor canvas an unconditional iframe. Custom ACF blocks registered at block version 1 or 2, which is what you get by default, cannot draw their field form inside that iframe, so ACF moves the fields out of the block and into the right-hand sidebar. On some setups they also stop saving.
Be clear about the blast radius, because it is narrower than the panic suggests. Core blocks work. Native custom blocks work. Ordinary ACF field groups on posts and pages work. Only the custom ACF blocks your own theme or plugin registers break. And updating ACF does not fix it: we hit this on ACF Pro 6.6.2, and the build where we isolated the root cause ran 6.8.8, the current release, which broke in exactly the same way.
Your theme did not change. ACF did not change. One line of core JavaScript changed. If you register ACF blocks from a block.json with no apiVersion, which is the arrangement every ACF tutorial shows, this hits you the moment core reaches 7.1. Two things fix it today, and neither works alone: pin core to 7.0.2 with auto-updates off, then ship a small editor script that forces your blocks back to mode: 'edit'. We hit this on a live site on 20 August 2026 and spent hours patching our own block code before anyone looked at core. The check that would have saved those hours is two grep commands, and it sits below.
ACF blocks in the sidebar: what you are looking at
You insert your custom ACF block into a post. Instead of the editable fields appearing inside the block, you get a read-only preview in the canvas and the fields turn up in the Block tab of the right-hand sidebar. On our production site it presented differently and worse. The fields still accepted typing and still displayed what you typed, then lost it on save. post_modified updated on every save. The block attributes did not. To the person editing, the site simply looked like the backend had come unplugged from the front end, which is a hard thing to file a useful bug report about.
The confusing part, and the reason this is close to unsearchable, is that it usually only hits the first block on the page. Insert a second block, even the same block type, and that one behaves normally with its fields inline. That asymmetry sends you looking for a bug in your own block, and there is no bug in your own block. We know because we looked for it first.
You are not alone on the timing. The ACF support forum thread “Blocks appearing in the sidebar after updating to WordPress 7.1” opened on 20 August 2026, the same day our production site broke, with developers reporting that the sidebar is unreadable at 280px and that they could no longer edit their sites at all. If you found this page by searching the symptom, a lot of people searched it the same week.
ACF blocks in the sidebar: what is not affected
The narrow blast radius is what makes this so easy to misdiagnose. Core blocks work normally. Native custom blocks with a save() or a React edit component work normally, because their authors wrote them for an iframed canvas in the first place. Ordinary ACF field groups work normally too, because they render as metaboxes in the top-level document, where the iframe never reaches them.
One thing breaks: a custom block registered through ACF at block version 1 or 2. If you are seeing ACF blocks in the sidebar, that is the combination you are running. On our own site 12 field groups sit on blocks and every one of them broke, while the rest are metaboxes on page templates and post types that carried on working. Register no custom ACF blocks and none of this reaches you, so update on the normal schedule.
Check your own install in ten seconds
Run these two commands in your WordPress root. They read core files only and change nothing.
grep -c "shouldIframe" wp-includes/js/dist/editor.js
grep -rl "disableIframe" wp-includes/js/dist/On 7.0.2 the second command lists four files. On 7.1 it lists none, because disableIframe no longer exists anywhere in the editor bundles. Zero files and ACF blocks in the sidebar are the same fact, seen from two directions. That one difference is the entire bug. We ran both against a stock WordPress 7.1 download and against the 7.0.2 install this site runs on, and here is what came back.
| What we grepped for | WordPress 7.0.2 | WordPress 7.1 |
|---|---|---|
useShouldIframe | present, edit-post.js:2211 | absent from every file |
hasV3BlocksOnly | present | absent from every file |
disableIframe | 4 files under wp-includes/js/dist/ | 0 files |
Value handed to BlockCanvas | shouldIframe: !disableIframe | shouldIframe: true, editor.js:95008 |
Root cause 1: WordPress 7.1 always iframes the canvas
Up to and including 7.0.2, core decided per post whether to iframe the editor canvas. The decision lived in a hook called useShouldIframe in wp-includes/js/dist/edit-post.js. This is the compiled 7.0.2 source, comments and all.
return (
// If the Gutenberg plugin is active, we ALWAYS use the iframe for
// consistency across the post and site editor. We plan on enforcing
// the iframe in the future, so Gutenberg both serves as way for us
// to warn plugin developers and for plugin developers to test their
// blocks easily.
isGutenbergPlugin ||
getDeviceType() !== "Desktop" ||
["wp_template", "wp_block"].includes(getCurrentPostType()) ||
unlock(select3(import_block_editor.store)).isZoomOut() ||
// Finally, still iframe the editor if all present blocks are v3
// (which means they are marked as iframe-compatible).
[...new Set(getClientIdsWithDescendants().map(getBlockName))]
.map(getBlockType)
.filter(Boolean)
.every((blockType) => blockType.apiVersion >= 3)
);Read the last clause. Core iframed the canvas only if every block present carried API version 3 or higher. One API version 2 block anywhere in the post, an ACF block for instance, and the whole canvas stayed un-iframed. That is the escape hatch classic themes with ACF blocks have been standing on for years, nearly all of them without knowing it existed.
Now read the comment above it. “We plan on enforcing the iframe in the future, so Gutenberg both serves as way for us to warn plugin developers.” Core shipped that warning inside the compiled bundle of every WordPress install for months. Nobody reads compiled bundles until something breaks.
What WordPress 7.1 removed
In 7.1 the hook is gone. useShouldIframe does not appear in the 7.1 build at all, and wp-includes/js/dist/editor.js hands BlockCanvas a literal instead.
jsxs( BlockCanvas, {
shouldIframe: true,
contentRef,
styles: iframeStyles,
height: "100%",
...
} )hasV3BlocksOnly, the selector behind that final clause, is gone too, and so is disableIframe. Note what did not change: BlockCanvas still accepts a shouldIframe prop, so the capability is still there in the block editor package. The editor package simply stopped passing anything but true. There is no filter, no constant and no setting to opt out, on the PHP side or the JS side. We grepped 7.1 for one before writing this.
If you want this explained from core’s side rather than ACF’s, Gutenberg Times published a thorough walkthrough for block developers in July 2026, a month before 7.1 landed. It is the best account of the mechanism there is, and it does not mention ACF once. That gap is why this article exists.
Why an iframe breaks ACF block version 2
An ACF block at block version 1 or 2 renders its edit form as ordinary markup driven by ACF’s jQuery field logic, in the same document as the rest of the admin. An iframed canvas is a separate document, so that machinery has nothing to attach to. ACF’s fallback is to render the fields into InspectorControls, which is the right-hand sidebar, and that is the documented behaviour for mode: preview. What you are seeing is not a crash. It is a fallback doing exactly what its author wrote it to do, in a situation nobody expected it to be in.
Here is the part that makes this everyone’s problem instead of an edge case. ACF defaults a block to version 2 when block.json says nothing.
$default_acf_block_version = apply_filters( 'acf/blocks/default_block_version', 2, $settings );It then derives the API version from that. A block.json omitting both apiVersion and acf.blockVersion, which is the minimal idiomatic ACF block, lands on block version 2 and API version 2. That is precisely the combination WordPress 7.1 stopped accommodating. We checked ACF Pro 6.6.2 (pro/blocks.php:67) and 6.8.8. Both set the same default, so upgrading ACF does not move you off it by itself.
Updating ACF does not fix it
The first instinct is that this is an ACF bug and the next ACF release will patch it. Two versions say otherwise. We hit it on ACF Pro 6.6.2. The build where we isolated the root cause was running 6.8.8, the current release, and it failed in exactly the same way: same iframed canvas, same fields pushed into the inspector, same silent failure to save. Nothing between those two versions changes the outcome, so upgrading the plugin is not the escape route it looks like.
That stops being surprising once you know where the default comes from. acf/blocks/default_block_version returns 2 in both releases, so a block.json that says nothing about versions gets block version 2 in both. What you are watching is the documented behaviour of block version 2 inside an iframe, not a regression ACF introduced. ACF is doing precisely what it says it does, in a context that did not exist when ACF specified that behaviour.
ACF states the position plainly rather than hopefully. In ACF’s own documentation for Blocks V3, Edit Mode “has been removed and replaced with a slide-out sidebar/modal”, and “the concept of modes no longer exists”. No setting in a newer ACF puts a version 2 field form back inside an iframed canvas, because the editing model that form belonged to is the thing ACF retired. Update ACF for everything else in its changelog. Then come back and pin core anyway.
What we measured
Root cause 2: ACF resets the block’s mode to preview
This one is older than 7.1 and independent of it. We were already working around it under WordPress 7.0. ACF does not read the block’s mode from block.json at render time. It writes a mode attribute onto every block instance and keeps it in the post content. Measured on a fresh post: insert one block, select it, insert a second.
{
"theme/faq": { "mode": "preview", "fieldsInBlock": 0, "fieldsInSidebar": 4 },
"theme/cta": { "mode": "edit", "fieldsInBlock": 4, "fieldsInSidebar": 0 }
}Both blocks declare "mode": "edit" in block.json. The one that lost selection came out at preview. The one still selected stayed at edit. The value persists in the saved content, and reselecting the block does not restore it.
That is the answer to “why only the first block”. The first block you insert is the first one to lose focus, because you click away from it to insert the second. Its mode settles on preview and stays there. The block you inserted last still has focus, so it still reads edit and looks fine. Insert a third and the second one breaks too. It has nothing to do with block type and everything to do with insertion order, which is why comparing two “identical” blocks in the same post teaches you nothing.
Why you cannot just click it back
The usual advice is to use the mode toggle in the block toolbar. But the recommended metadata for a block your editors edit inline is this.
"supports": {
"align": [ "wide", "full" ],
"anchor": true,
"mode": false
}"mode": false removes the toggle. It is there for a good reason, to stop editors flipping a block into a preview state you never designed, and it means that once ACF puts the block into preview, nothing in the interface can take it out. The advice and the recommended config cancel each other out.
How we traced ACF blocks in the sidebar to one line of core
Guessing at this from the markup is hopeless. The working block and the broken block were byte for byte identical in structure. What settled it was driving the real editor with Playwright and reading state straight out of the Gutenberg data store instead of off the screen.
const sel = wp.data.select( 'core/block-editor' );
const b = sel.getBlock( clientId );
const node = document.querySelector( `[data-block="${ clientId }"]` );
const insp = document.querySelector( '.block-editor-block-inspector' );
return {
mode: b.attributes.mode ?? null,
canvasIsIframe: !! document.querySelector( 'iframe[name="editor-canvas"]' ),
fieldsInBlock: node ? node.querySelectorAll( '.acf-block-fields .acf-field' ).length : -1,
fieldsInSidebar: insp ? insp.querySelectorAll( '.acf-field' ).length : 0,
previewClass: node ? node.className.includes( 'acf-block-preview' ) : null,
};Running the same probe against a broken install and a working one produced the comparison that reduced the problem to the WordPress version: canvasIsIframe false against true, 86 ACF fields in the canvas against 0, and 0 fields in the sidebar against all of them, with identical block configuration on both machines. After that, reading the two edit-post.js builds side by side explained the rest in about a minute.
We now treat this as a rule on every editor bug. It is not diagnosed and not fixed until the real editor says so. Static analysis of block code lies about editor behaviour, because the editor resolves that behaviour at runtime from two version numbers that live in two different projects.
The fix for ACF blocks in the sidebar, in two parts
Getting ACF blocks in the sidebar back into the block takes two changes, and neither one works without the other. The first stops the iframe. The second stops ACF from parking your blocks in preview once they lose focus.
Part 1: pin core to 7.0.2
wp db export db-before-downgrade.sql --add-drop-table
tar czf core-backup.tar.gz wp-admin wp-includes *.php
wp core update --version=7.0.2 --force--force overwrites core only and leaves wp-content untouched. Take both backups first. The database keeps the higher db_version from 7.1, which WordPress tolerates by skipping the upgrade routine, but there is no supported way to migrate the schema backwards. That export is your only way out if the rollback goes wrong.
Then stop core from climbing back up. In wp-config.php, and leave the comment in, because the next person to read that file will otherwise assume the pin is paranoia.
/*
* Core is pinned to 7.0.2 on purpose.
*
* WordPress 7.1 removed the `hasV3BlocksOnly` check and hard-codes
* `shouldIframe: true`, so the editor canvas is always an iframe. ACF blocks at
* block version 2 cannot draw their field form inside that iframe, and ACF
* falls back to putting the fields in the right-hand inspector instead of in
* the block. Letting core update itself would silently undo that.
*/
define( 'WP_AUTO_UPDATE_CORE', false );wp option update auto_update_core_major disabledPart 2: keep the blocks in edit mode
The pin fixes the iframe. It does not fix the mode reset, which was breaking blocks under 7.0 already. This goes in assets/js/editor-blocks.js.
( function ( wp ) {
if ( ! wp || ! wp.data || ! wp.domReady ) {
return;
}
var PREFIX = 'yourtheme/';
wp.domReady( function () {
var editor = wp.data.select( 'core/block-editor' );
var dispatch = wp.data.dispatch( 'core/block-editor' );
if ( ! editor || ! dispatch ) {
return;
}
wp.data.subscribe( function () {
var ids = editor.getClientIdsWithDescendants();
for ( var i = 0; i < ids.length; i++ ) {
var id = ids[ i ];
var name = editor.getBlockName( id );
if ( ! name || name.indexOf( PREFIX ) !== 0 ) {
continue;
}
var attrs = editor.getBlockAttributes( id );
// Guard on the value so we only dispatch when it drifts. This
// keeps the subscription from looping on its own update.
if ( attrs && attrs.mode !== 'edit' ) {
dispatch.updateBlockAttributes( id, { mode: 'edit' } );
}
}
} );
} );
}( window.wp ) );Two details decide whether this helps or hurts
Both are easy to get wrong, and both are expensive when you do.
- The value guard is not optional.
wp.data.subscribefires on every store change, including the one your ownupdateBlockAttributescall causes. Drop theattrs.mode !== 'edit'check and you get an infinite dispatch loop that pins a CPU core and makes the editor unusable. We know what that looks like. - Match on a namespace prefix, not a hard-coded list of block names. A literal array is one more thing to forget when you add a block six months from now, and the failure is silent.
Enqueue it on the editor only
Nothing here belongs on the front end.
function yourtheme_enqueue_block_editor_assets() {
$editor_js = get_template_directory() . '/assets/js/editor-blocks.js';
if ( file_exists( $editor_js ) ) {
wp_enqueue_script(
'yourtheme-editor-blocks',
get_template_directory_uri() . '/assets/js/editor-blocks.js',
array( 'wp-data', 'wp-dom-ready' ),
(string) filemtime( $editor_js ),
true
);
}
}
add_action( 'enqueue_block_editor_assets', 'yourtheme_enqueue_block_editor_assets' );Use enqueue_block_editor_assets for your editor CSS too. Do not reach for add_theme_support( 'editor-styles' ) with add_editor_style() here. That hands the theme ownership of the canvas typography, and on a classic theme with an un-iframed canvas your colours and fonts leak straight into the admin chrome.
Verify it in the editor, not in your head
Insert the same block three times into a fresh post, which is the exact scenario that used to fail.
| Position | mode | Fields inline | Fields in sidebar |
|---|---|---|---|
| 1st | edit | 4 | 0 |
| 2nd | edit | 4 | 0 |
| 3rd | edit | 4 | 0 |
Then walk the states that were breaking it: select the first block, select the second, clear the selection entirely. mode must read edit at every step, and .acf-block-preview must never appear in the class list. After the rollback on this site the probe reported 127 ACF fields in the canvas and 0 in the inspector, typed text reaching both the block attributes and the database, and no console errors. That is the bar. A block that renders correctly on the front end proves nothing about any of it.
Five fixes for ACF blocks in the sidebar that did not work
We measured every one of these on WordPress 7.1 before the rollback. They are here so nobody repeats them.
| What we tried | What actually happened |
|---|---|
A shim forcing the mode attribute back to edit, on 7.1 | Fields render inline and still do not save. They also duplicate into the inspector, so you get two copies of every field. |
"blockVersion": 3, ACF Blocks V3 | Saves correctly. On ACF 6.6.2 it ignores mode entirely and always puts the fields in the inspector panel, so it trades a save bug for a layout you did not ask for. |
Re-dispatching the jQuery change event from an iframe listener | Unreliable. Sometimes it lands, usually it does not, and you cannot tell which from the UI. |
acf.serialize() plus updateBlockAttributes directly | Wipes block data. Do not run this against content you care about. |
Passing TinyMCE a target instead of init.selector | Throws, and the fields vanish completely. |
The expensive part was not any of those individually. It was the order we did them in. Hours went into patching a vendor bug before anyone read the vendor’s release notes, and before anyone diffed our block.json against a site on the same server where the same blocks still worked. Check the vendor first. Diff against a known-good reference second. Patch last. That reference site cost nothing to check and would have isolated the variable in about five minutes, because it ran an identical ACF version on older core, which is the one comparison that mattered.
The forward-looking alternative, and why we did not take it
Setting "blockVersion": 3 and staying on 7.1 is the answer that ages well, and as a data-integrity fix it works: version 3 is built for the iframed canvas and saves correctly. Read ACF’s own description of it before assuming it gives you back what you had. In ACF’s own documentation for Blocks V3, Edit Mode “has been removed and replaced with a slide-out sidebar/modal” and “the concept of modes no longer exists”. The block sits on the canvas as a live preview, and you edit the fields in the sidebar or in a roomier Expanded Editor.
Does version 3 fix ACF blocks in the sidebar?
No, and that settles the question this article turns on. Migrating to version 3 does not restore in-canvas field editing, it replaces it. If your editors need a form inside the block, version 3 is not the fix, it is the same sidebar with a better door on it. What version 3 does add is autoInlineEditing, which makes some rendered values editable in the preview itself, and that carries its own bill. With it on, ACF hands your render template pre-rendered strings where you expected arrays, so $image['ID'] and foreach ( $repeater as $row ) throw Cannot access offset of type string on string. It does not cover Repeater or Flexible Content either, and 9 of our 12 block field groups are repeater-based. Migrating means rewriting every render template, not flipping a flag.
One mitigation is worth knowing if you do migrate. Setting "hideFieldsInSidebar": true keeps the fields out of the cramped inspector and confines them to the slide-out panel, which is a genuine usability improvement on the default. It puts nothing back inside the block. Treat it as making the new model tolerable, not as a way back to the old one.
There is nothing to filter, and patching core survives exactly until the next update and then silently reverts. Pinning is the honest choice while your render templates are not ready for version 3. It is reversible, the comment documents it in the config file where the next person will find it, and it buys time without rewriting a single render template.
Who will never see ACF blocks in the sidebar
If your ACF fields are all metaboxes on posts, pages or custom post types, none of this touches you. Metaboxes render in the top-level document and the canvas iframe never reaches them. The same goes for a block theme using native blocks with no ACF blocks at all. If your ACF blocks already declare "blockVersion": 3 and your render templates handle it, 7.1 is fine and you should update on the normal schedule.
And if you maintain one small site with two ACF blocks and no repeaters, migrating to block version 3 is very likely less work than carrying a version pin for an unknown number of months. We would not pin a site we could migrate in an afternoon. Pinning core is a real cost: you are declining security patches on the schedule the project ships them, and you are taking on the job of watching for the release that lets you undo it. That watching is ongoing work, and it is most of what a WordPress care plan actually buys. That trade only makes sense when the migration is genuinely large.
When to remove the workaround
Be realistic about what you are waiting for. ACF has retired the editing model that block version 2 fields belonged to, so a release putting that form back inside an iframed canvas is unlikely rather than merely late. The exit that actually exists is a version 3 migration, and its trigger is your own code rather than somebody’s release note: when your render templates no longer assume arrays, and your editors have accepted a slide-out panel, the pin has done its job. At that point:
- Migrate the blocks to
"blockVersion": 3and rewrite every render template that assumed arrays. - Update ACF Pro.
- Remove
WP_AUTO_UPDATE_COREfromwp-config.phpand re-enableauto_update_core_major. - Update core, then re-run the verification above before deleting
editor-blocks.js. Themodereset is a separate ACF behaviour and may well outlive the iframe problem.
Frequently asked questions
How do I know if ACF blocks in the sidebar will hit my site?
Open any block.json in your theme or plugin and look for two keys: apiVersion at the top level and blockVersion inside the acf object. If both are missing, ACF defaults you to block version 2 and API version 2, which is the affected combination. That default is unchanged across ACF Pro 6.6.2 and 6.8.8, so your ACF version does not rescue you. The second check is on core itself: run grep -rl disableIframe wp-includes/js/dist/ in your WordPress root. Four files means you are on 7.0.x and safe for now. Zero files means the canvas is always an iframe. Do both checks on a staging copy before you let core update, because after the update the only way back is a restore or a forced downgrade. Checking on staging is how you avoid meeting ACF blocks in the sidebar on a live site.
Will updating ACF fix this?
No, and this is the most common wrong turn. We hit it on ACF Pro 6.6.2, and the build where we isolated the root cause ran 6.8.8, the current release. Both produced ACF blocks in the sidebar in exactly the same way, with the same silent failure to save. Nothing between those versions changes the block version default: acf/blocks/default_block_version still returns 2, so a block.json that says nothing about versions still lands on block version 2, and block version 2 inside an iframe behaves exactly as documented. ACF’s own Blocks V3 documentation is blunter than most people expect: Edit Mode has been removed and replaced with a slide-out sidebar/modal, and the concept of modes no longer exists. No newer ACF setting puts a version 2 field form back inside an iframed canvas. Update ACF for the rest of its changelog, not for this.
Why are only some of my ACF blocks in the sidebar?
Because ACF stores the block mode as a per-instance attribute in the post content, not as a property of the block type, and it settles on preview for any block that is not currently selected. The first block you insert is the first to lose focus, since you click away from it to insert the second, so its mode is written as preview and stays there. The block you inserted last still has focus and still reads edit. Insert a third and the second one breaks too. It has nothing to do with which block type you used, which is exactly why comparing a working block against a broken one in the same post tells you nothing useful. Once you know it is insertion order, the whole thing stops looking like a block bug and starts looking like a state bug, which is where it actually lives.
Is downgrading WordPress safe?
Downgrading core files is safe and reversible. Downgrading the database is not. wp core update –version=7.0.2 –force replaces wp-admin, wp-includes and the root PHP files and leaves wp-content alone, so your themes, plugins and uploads are untouched. The database keeps the higher db_version that 7.1 wrote, and WordPress tolerates that by skipping the upgrade routine rather than by migrating anything backwards. In practice this works, and a pinned 7.0.x is what we run in production today. Ours reads 7.0.4 rather than 7.0.2, because the host moved it after we pinned it, which is its own warning. Take a full database export before you start anyway, because if a plugin has already written data in a 7.1-only format, that export is your only route back. The bigger risk is not the downgrade itself, it is forgetting to disable auto-updates afterwards and having the problem quietly return.
Can I just set blockVersion 3 and update to 7.1?
Yes if you accept a different editing model, no if you were hoping for the old one back. Block version 3 is built for the iframed canvas and saves correctly under 7.1, so as a data-integrity fix it works. What it does not do is get your ACF blocks in the sidebar back into the block. ACF’s documentation states that Edit Mode has been removed and replaced with a slide-out sidebar/modal, and that the concept of modes no longer exists, so the block becomes a live preview while you edit in the sidebar or the larger Expanded Editor. Setting hideFieldsInSidebar to true keeps the fields in the roomier slide-out panel rather than the cramped inspector. The second cost is your templates: autoInlineEditing hands them pre-rendered strings where they expected arrays, so anything doing $image[‘ID’] or looping a repeater will throw. Repeater-heavy blocks, budget for rewriting every render template.
Will WordPress add a filter to turn the iframe off?
Nothing suggests it. The 7.0.2 source carried a comment stating the plan directly: the Gutenberg plugin always iframed the canvas so that it would serve as a warning to plugin developers, and the intention to enforce the iframe everywhere was stated in that comment months before 7.1 shipped. Removing the escape hatch was the plan, not an accident, so treat any workaround as temporary by design. The BlockCanvas component still accepts a shouldIframe prop, so the capability technically survives inside the block editor package, but the editor package no longer passes anything except true and there is no PHP or JS hook that reaches it. The realistic path forward is a version 3 migration on your side, not core reversing course and not ACF reviving an editing model it has already retired. Plan the migration, and use the pin to buy the time it takes.