ACF Blocks Lost Their Edit Pencil in WordPress 7.1

WordPress 7.1, released August 19, 2026, loads the post editor inside an iframe on every site, every time. ACF blocks built on ACF's older block format (ACF Blocks V2) depend on wp-admin scripts and styles that never load inside that iframe, so their in-canvas edit form stops working. The block is forced into preview, the edit toggle disappears, and the fields get squeezed into the narrow settings sidebar. The fix is ACF PRO 6.8.9 or later plus a migration to ACF Blocks V3, with ACF's official compatibility plugin or a short hold on WordPress 7.0.7 as the bridge.

Updated October 13, 2026: an earlier version of this post recommended forcing "mode": "edit" in block.json. That does not restore editing on 7.1. This version replaces it with the fix ACF itself recommends.

What changed in WordPress 7.1

Until 7.1, whether the post editor ran in an iframe depended on the content. WordPress 6.3 iframed it only when every registered block used block API version 3. WordPress 7.0 narrowed that to the blocks in the post itself, so a single apiVersion 2 block on the page dropped the editor back to the old, non-iframed mode. Most ACF sites never saw the iframe because their own blocks kept switching it off.

That fallback is gone. The core dev note on iframed editor changes in 7.1 says the post editor "is always iframed, regardless of the theme type, the block API versions of the registered blocks, or the block API versions of the blocks in the content." The 7.1 Field Guide adds that this includes sites that register legacy meta boxes. There is no opt-out filter in core.

The iframe has its own document and window. Only content assets load inside it:

• Loaded in the canvas: anything enqueued on enqueue_block_assets, plus each block's style, script and editorStyle handles from block.json.
• Not loaded in the canvas: scripts and styles enqueued on admin_enqueue_scripts, enqueue_block_editor_assets or wp_enqueue_scripts, and each block's editorScript. Those stay in the parent admin page (or, for wp_enqueue_scripts, the front end only).

That split is the whole story behind the ACF breakage.

Why ACF blocks break in the iframe

The ACF Blocks V2 edit form is an admin form rendered inside the editor canvas. It needs ACF's admin CSS, ACF's admin JavaScript, and a set of jQuery-based field libraries (date picker, color picker, enhanced selects, Google Map). ACF said back in 2023 that the edit form cannot be supported inside the iframe, because those third-party libraries cannot be pointed at a different document. In the ACF PRO 6.8.9 release post, the ACF team describes the 7.1 result directly: V2 fields are forced into preview mode and editing happens only in the right-hand sidebar.

What editors and developers see on an affected site:

• Stuck in preview. The toolbar toggle that switched a block to its field form is gone. Editors click the hero block and get the rendered hero with nowhere to type.
• Fields in a 280px sidebar. Text fields survive. Repeaters, Flexible Content and WYSIWYG fields become close to unusable.
• Blank or broken previews on edit-only blocks. Blocks you shipped as "mode": "edit" with no designed preview now show their render template in the canvas, often unstyled, half empty or blank.
• Missing styles. CSS you loaded on an admin hook no longer reaches the canvas, and admin styles that used to leak into previews (blue admin buttons, form styling) are gone too.
• Scripts that never run. Sliders, maps and accordions in previews stay blank when their script is enqueued on wp_enqueue_scripts, as a viewScript, or as an editorScript. The admin page's jQuery lives in the parent window; inside the canvas, jQuery exists only if a script loaded there declares it as a dependency.

Users on the ACF support forum reported the sidebar symptom the day after release, and some have also reported WYSIWYG previews going blank in iframe mode. Treat that last one as a user report until ACF confirms it.

Nothing throws an error and nothing logs. Uptime is green and the front end looks fine. The client assumes they broke something, waits a day, then calls you at 4:45 on a Friday. If your first instinct is to treat it like a downed site, read our 20-minute triage order for a site you suddenly cannot access and rule that path out fast, because this failure lives entirely inside the editor.

Why forcing edit mode does not help

The edit form is what cannot render inside the iframe, so asking ACF for edit mode asks for the one thing it can no longer draw. On ACF PRO 6.8.9 and later, a V3 block that still carries the legacy combination of "mode": "edit" with supports.mode set to false is treated as "no preview" and shows a placeholder with an Edit Block button instead. That is better than a blank box, but it comes from V3, not from the mode setting.

How to check every client site

Give this 20 minutes across the portfolio. Per site you need the core version, the ACF PRO version, and which ACF blocks still run on V2. A site on 7.0.x is not affected yet. A site that uses ACF only for field groups on posts and pages is not affected at all.

Run this per site from the WordPress root:

wp core version
wp plugin get advanced-custom-fields-pro --field=version

# Registered ACF blocks (assumes the acf/ namespace)
wp eval 'print_r( array_keys( array_filter( WP_Block_Type_Registry::get_instance()->get_all_registered(), fn( $b ) => str_starts_with( $b->name, "acf/" ) ) ) );'

# block.json files with an "acf" key, and the ACF block version each declares
grep -rl --include=block.json '"acf"' wp-content/themes wp-content/plugins wp-content/mu-plugins 2>/dev/null \
  | while read -r f; do printf '%s: %s\n' "$f" "$(grep -o '"blockVersion"[^,}]*' "$f" || echo 'no blockVersion')"; done

# Blocks registered in PHP
grep -rn --include='*.php' --exclude-dir=advanced-custom-fields-pro -E "acf_register_block_type|acf_block_version" \
  wp-content/themes wp-content/plugins wp-content/mu-plugins 2>/dev/null

If you manage sites through one control plane, script it across the fleet and dump the output into a sheet. Then open one page per site that uses an ACF block and click the block. If the fields only show up in the sidebar, or the preview is blank or unstyled, the site is affected.

Use the results to sort each site:

The automatic switch in 6.8.9 matters. Per the ACF changelog, blocks registered through acf_register_block_type() or block.json without an explicit version now default to V3 on WordPress 7.1 or later. Blocks that declare a version keep it, so a theme that pinned "blockVersion": 2 years ago stays broken after the update.

The fix: update ACF PRO, then migrate to ACF Blocks V3

Step 1: update ACF PRO

ACF PRO 6.8.9 (August 27, 2026) is the release built for 7.1: the V3 default for unversioned blocks, the renderPreview option, and automatic handling of legacy edit-only blocks. Install the current release, 6.8.10 (September 10, 2026), which also carries a batch of security hardening. V3 itself needs ACF PRO 6.6 or later, and inline editing needs 6.7 or later.

wp plugin update advanced-custom-fields-pro

PRO updates arrive through ACF's own updater, so this only works on sites with an active licence key.

Step 2: move each block to V3

There are two version numbers in play, and they are easy to mix up:

• apiVersion is the WordPress block API version, at the top level of block.json. Core now only accepts 3 in its schema and has logged a console warning for lower values since WordPress 6.9.
• acf.blockVersion is ACF's own block format. Setting it to 3 is what switches the block to the V3 editing experience. ACF's Blocks V3 guide documents it.

Set both. A migrated block.json for a hero block looks like this:

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "acf/hero",
  "title": "Hero",
  "category": "theme",
  "icon": "cover-image",
  "style": "file:./hero.css",
  "editorStyle": "file:./hero-editor.css",
  "script": "theme-hero",
  "acf": {
    "blockVersion": 3,
    "renderTemplate": "hero.php"
  }
}

Drop acf.mode and supports.mode while you are in there. ACF V3 has no modes: blocks always show the render template, and fields open in the sidebar or in the larger Expanded Editor from the pencil icon.

Three optional acf keys from the ACF block.json reference shape the editing experience:

• "renderPreview": false shows a placeholder with the block's icon, title and an Edit Block button instead of a live preview. Use it for blocks that never had a preview. The front end renders normally. Needs 6.8.9 or later.
• "hideFieldsInSidebar": true keeps fields out of the narrow sidebar so all editing happens in the Expanded Editor. Needs 6.6.2 or later.
• "autoInlineEditing": true lets editors type straight into text that comes from a single ACF field. Needs 6.7 or later.

For blocks registered in PHP, add the same versions to the registration array:

add_action( 'acf/init', function () {
	acf_register_block_type(
		array(
			'name'              => 'hero',
			'title'             => 'Hero',
			'render_template'   => get_theme_file_path( 'blocks/hero/hero.php' ),
			'category'          => 'theme',
			'icon'              => 'cover-image',
			'api_version'       => 3,
			'acf_block_version' => 3,
		)
	);
} );

ACF staff confirm that the PHP equivalents of the optional keys are render_preview and hide_fields_in_sidebar. If you have dozens of unversioned blocks, the acf/blocks/default_block_version filter returning 3 opts them all in at once, but it never overrides a block that declares its own version.

Step 3: load preview assets inside the iframe

V3 renders your template in the canvas, so the template's CSS and JavaScript have to load there too. Put them on the block, not on an admin hook:

• Styles: style loads on the front end and in the canvas. editorStyle loads in the canvas only, for editor-specific tweaks.
• Scripts: script loads on the front end and in the canvas. viewScript is front end only, and editorScript runs in the parent admin window, so neither runs a slider inside the preview.
• Dependencies: a file: path in block.json cannot declare jQuery as a dependency without a generated .asset.php file. For a classic theme, the simpler route is registering the script yourself and referencing its handle, as the "script": "theme-hero" line above does:

add_action( 'init', function () {
	wp_register_script(
		'theme-hero',
		get_theme_file_uri( 'blocks/hero/hero.js' ),
		array( 'jquery' ),
		wp_get_theme()->get( 'Version' ),
		array( 'in_footer' => true )
	);

	register_block_type( get_theme_file_path( 'blocks/hero' ) );
} );

For assets that are not tied to one block, such as a shared slider library, use enqueue_block_assets. It fires in the canvas and on the front end, and an is_admin() check limits a file to the editor. Inside your scripts, find elements through the block element's ownerDocument rather than the global document of the admin page, which is the pattern the block editor handbook migration guide recommends. If you used the enqueue_assets callback of acf_register_block_type(), confirm on staging that its files reach the canvas before you rely on it.

ACF render templates also receive $is_preview, which you can use to output a lighter, script-free version of a heavy block inside the editor.

Step 4: tell the editors

V3 edits differently. Fields live in the sidebar and the Expanded Editor, not in the block body. Send clients a two-line note and a screenshot before they find it themselves. A changed workflow they were told about is a training item. A changed workflow they discover is a support ticket.

Short-term options while you migrate

Option 1: ACF's compatibility plugin (preferred)

ACF published acf-blocks-v2-iframe-compatibility alongside 6.8.9. When a registered ACF block is still on V2, it turns off the iframed canvas on the block editor screen so V2 edit mode works again. While it is active, it also pins unversioned blocks to V2. Sites whose blocks are all on V3 get no change.

It installs from the GitHub ZIP like any plugin. ACF calls it a temporary bridge that may break with future WordPress changes, so treat it that way: it buys weeks, and it keeps the site on the current, patched WordPress 7.1.3. Avoid unofficial "force edit mode" plugins; ACF staff have advised against them.

Option 2: hold on WordPress 7.0.7

Rollback makes sense when a site has a dozen V2 blocks, the client publishes daily, and you cannot test the compatibility plugin today. Do it in this order:

• Take a fresh full backup, files and database, and confirm you can restore it. Our WordPress backup strategy guide covers what a usable backup includes.
• Run the rollback on staging first: wp core update --version=7.0.7 --force
• Run wp core update-db, then load the editor and confirm the V2 edit toggle is back.
• Stop the next automatic major update from undoing it: wp config set WP_AUTO_UPDATE_CORE minor. The site still takes 7.0.x security releases. If your host manages core updates, tell them about the hold.
• Repeat on production during a low-traffic window.
• Set a calendar reminder for 14 days out.

The 7.0 branch is still receiving security releases (7.0.7 is the latest), but WordPress only fully supports the current version, and older branches get fixes as a courtesy. Give yourself a fixed window rather than an open-ended pause. We wrote about this tradeoff in our WordPress update strategy for core, plugins, and themes. A two-week hold with a reminder attached is disciplined; a six-month hold is a liability.

Never roll back production without staging it first. If your current host does not give you a staging environment per site, this regression is a decent argument that the hosting line item is costing you more than it saves.

Testing checklist on staging

Before the V3 migration, or the 7.1 update itself, goes to production, work through this on a staging copy with real content:

• Core reports 7.1.3 and ACF PRO reports 6.8.10 or later.
• Every ACF block either declares "blockVersion": 3 or is deliberately on V2 with the compatibility plugin active.
• Open the two or three templates the client edits most. Click every ACF block: the pencil opens the Expanded Editor, fields save, and the preview updates.
• Repeaters, Flexible Content and WYSIWYG fields are usable in the Expanded Editor, not only in the sidebar.
• Previews are styled. Open the browser devtools, select the editor canvas iframe, and confirm your block CSS loaded there.
• Sliders, maps, tabs and accordions initialise in the preview. Check the console for errors such as jQuery is not defined.
• Required-field validation fires when you save, which is when V3 shows errors.
• Insert a new block, duplicate one, and move one inside a group or column, then save and reload.
• Compare the front end before and after. It should be identical.
• Log in as the client's editor role, not as an administrator, and repeat one edit.

What an emergency ACF fix costs an agency

Run the numbers on a 40-site portfolio where 12 sites use ACF blocks. The engineering time is similar either way. The cost difference comes from everything attached to it when a client finds the problem first.

Across 12 affected sites, the staging path runs about $600 of internal time to find the problem. The client-reports-it path runs closer to $3,750, and almost none of it is billable, because nobody pays you to fix a problem the update caused. The V3 migration costs the same either way. What changes is whether you schedule it or the client schedules it for you. Then add the part that does not fit in a table: the retainer conversation three months later where the client remembers the week they could not edit their own homepage.

According to W3Techs, WordPress runs roughly 43% of all websites (2026), and ACF is one of the most widely deployed development dependencies inside it. A core change that touches ACF blocks lands on a lot of desks at once. The agencies that come out fine are the ones that saw it on staging on a Tuesday, not the ones that heard about it from a client on a Friday.

We broke down where this kind of non-billable time goes in what DIY WordPress hosting costs an agency every month. ACF block breakage is a textbook example: no server failed, no security incident happened, and the bill still arrives.

Why staging-first update testing catches this before the client calls

A staging-first workflow catches editor regressions because a human opens the editor before the update reaches production. There is no clever automation here, just a copy of the site, a core update, and five minutes of clicking blocks on the templates the client edits most.

At TopSyde, every site gets its own staging environment, and core updates run there first with a checklist that includes loading the block editor on real content rather than a blank test page. Our plugin and core update testing workflow walks through how the queue works, and our staging environment guide covers the mechanics if you want to build the same process on your current host.

When a change like the 7.1 iframe shows up, the update gets held on affected sites, the compatibility plugin or the V3 migration goes out to the ones that need it, and the client never learns there was a decision to make. That is what managed WordPress hosting is supposed to cover in 2026, and the difference between hosts is mostly whether anyone does it.

Monitoring runs 24/7 on our side. Human support answers in under 2 hours during business hours, which matters when you have a client on the phone and 12 sites to check.

Getting this off your plate

If you are reading this with a spreadsheet of client sites open, do the audit first: core version, ACF PRO version, block versions, ten minutes of clicking. Update ACF PRO everywhere, bridge the V2 sites with the compatibility plugin or a dated 7.0.7 hold, and schedule the V3 migrations.

Then look at why you found out about it here instead of from your host. Plans start at $89/mo per site with staging, per-site backups, and update testing included, and we handle the migration. See what is covered on the pricing page, check the technical spec sheet if you want the infrastructure detail, or look at how the agency program works if you are moving a portfolio rather than a single site. There is a 30-day money-back guarantee, so moving one site to test the workflow costs you a week of attention and nothing else.

Keep Reading on TopSyde

• WordPress 7.1 update: what changed and who should wait: the other 7.1 changes worth testing, including the new wp_pre_execute_ability filter.
• WordPress plugin and core update testing workflow: how a staging-first update queue works in practice.
• WordPress staging environments explained: what a usable staging copy needs.
• WordPress update strategy for core, plugins, and themes: how long to hold an update, and when not to.
• Managed hosting for agencies
• TopSyde pricing & plans

Frequently Asked Questions

Is the ACF block issue in WordPress 7.1 a bug in ACF or in core?

Neither, strictly. Core made a planned change: the iframed editor arrived in 6.3, block API version 2 has triggered console warnings since 6.9, and the 7.1 dev note announced the always-on iframe weeks before release. ACF Blocks V2 edit mode was never able to run inside that iframe, and ACF's answer is ACF Blocks V3, made the default for unversioned blocks in ACF PRO 6.8.9.

Does setting "mode": "edit" in block.json fix it?

No. The edit form is the part that cannot render inside the iframe, so forcing edit mode does not bring it back. On ACF PRO 6.8.9 and later, a V3 block with the old edit-only settings shows a placeholder with an Edit Block button, and ACF recommends setting renderPreview to false for that instead.

Will visitors see any change on the front end?

No. This is an editor change. Render templates produce the same front-end markup on V2 and V3, and renderPreview: false only affects the editor. Compare a few pages before and after on staging anyway, especially if you moved scripts from viewScript to script.

Do I need both apiVersion 3 and blockVersion 3?

Set both. apiVersion tells WordPress the block is built for the iframe, and current core expects 3. acf.blockVersion is what moves the block to ACF's V3 editing experience. Changing only apiVersion leaves an explicitly versioned V2 block on the old, broken edit form.

Can I just tell clients to use the block sidebar instead?

For a block with two or three text fields, yes, as a stopgap. For repeaters, Flexible Content and long WYSIWYG fields, the sidebar is too narrow to work in. ACF Blocks V3 gives those fields the Expanded Editor, and the compatibility plugin restores the old in-block form while you migrate.

How long should I stay on WordPress 7.0.x after rolling back?

Set a hard window of two to four weeks and put a reminder on the calendar. The 7.0 branch still receives security releases today, but only the current version is fully supported, so an indefinite hold trades an editor annoyance for a security exposure. The compatibility plugin is usually the better bridge because it keeps the site on 7.1.3.

Does every site running ACF PRO have this problem?

No. Sites that use ACF only for field groups on posts, pages and options are unaffected. Sites with ACF blocks are affected if those blocks still run on V2, which is every ACF block on ACF PRO older than 6.8.9 and any block that explicitly declares blockVersion 1 or 2 on newer releases. Run the audit rather than assuming either way.

Colton Joseph

Founder & Lead Developer

20+ years full-stack development, WordPress, AI tools & agents

Colton is the founder of TopSyde with 20+ years of full-stack development experience spanning WordPress, cloud infrastructure, and AI-powered tooling. He specializes in performance optimization, server architecture, and building AI agents for automated site management.

LinkedIn