Troubleshooting GT ACF Blocks

Blocks Don’t Appear in the Editor

ACF is not active. The plugin requires Advanced Custom Fields Pro 6.0+ or Secure Custom Fields. Check that one of these is installed and activated. An admin notice will appear if ACF is missing.

ACF Blocks troubleshooting starts from one diagnostic question: is ACF active and current? That single check resolves most blank-block reports. This lesson works through the rest of the failure modes in descending frequency, each with its diagnosis and fix.

block.json is invalid. A malformed block.json file will silently prevent registration. Validate your JSON with a linter. Check WP_DEBUG_LOG for error messages from register_block_type().

The block name doesn’t start with acf/. ACF blocks must have names prefixed with acf/. Other prefixes will not be picked up by ACF’s rendering system.

The block is disabled in the Block Manager. Blocks unchecked on the Performance & Block Manager card (Settings > ACF Blocks License) are not registered at all. Re-enable the block and save.

Fields Are Empty or Return False

ACF 6.7+ compatibility. If you’re calling get_field() directly in a block template, it may return false in ACF 6.7+. Switch to acf_blocks_get_field() and acf_blocks_get_repeater() from the compatibility layer. These functions fall back to reading from $block['data'] when get_field() fails.

REST API save format. Content saved via the REST API stores repeater data as flat indexed keys (field_0_subfield). The compatibility helpers handle this transparently, but get_field() does not.

Repeater Fields Show Empty in the Editor

Flat key format in saved content. If block content was saved via the REST API, repeater data is stored as flat keys. The render_block_data filter reconstructs these into the nested row-N format that ACF’s editor JavaScript expects. This runs automatically on admin and REST requests.

If repeater fields still appear empty after editing, check that the block’s field group has the correct location rule matching the block name.

Styles Don’t Appear in the Editor

The editor loads one consolidated CSS bundle (assets/css/editor-blocks.css, or a site-specific bundle when blocks are disabled through the Block Manager). If styles are missing:

1. Check the “Editor CSS bundle” row in the Diagnostics table on the Performance & Block Manager card. “Missing” means the bundle file is gone; re-save the Block Manager settings to rebuild the site-specific bundle.
2. Verify the style path in block.json is correct (e.g. "file:./my-block.css").
3. Check for theme or plugin CSS conflicts that may override block styles.
4. Clear your browser cache. The editor iframe can aggressively cache stylesheets.

Styles Load on Every Page

Block stylesheets should only load on pages where the block is used. This relies on wp_register_style() during init. If styles load globally:

1. Confirm the style is registered (not enqueued) during init.
2. Check that no other code is calling wp_enqueue_style() for the block’s style handle unconditionally.

Image Localizer Not Downloading Images

Images are detected as local. The localizer skips images from your site’s domain, subdomains, and Bunny CDN (*.b-cdn.net). Use the acf_blocks_is_local_image_url filter to check what’s considered local.

WP-Cron is not running. Since 2.9.0 downloads run in a background queue, not during the save request. If WP-Cron is disabled or stalled, queued images sit unprocessed. The “Queued image-localization posts” row on the Performance & Block Manager card shows the backlog, and “Process Image Queue Now” runs the queue immediately.

Upload directory not writable. The localizer saves images to wp-content/uploads/acf-blocks-plugin/images/. If this directory cannot be created or written to, downloads fail silently.

File validation fails. Downloaded files are validated as images. If wp_get_image_mime() cannot identify the file type (and it’s not an SVG), the download is discarded.

Star Rating Not Saving

Stale cached markup. Submissions go to the acf-blocks/v1/ratings REST route with a cache-safe token rendered into the block, so page caching is no longer the usual culprit. If ratings stopped working right after updating, purge the page cache so the new script and token markup are served; the legacy admin-ajax fallback keeps old cached pages working in the meantime.

localStorage blocking. The frontend script uses localStorage to prevent duplicate ratings. If localStorage is blocked (private browsing, certain browser settings), the “already rated” check may not work.

Post does not exist. The handler validates that the post ID corresponds to an existing post. Ratings for deleted posts are rejected. Server-side, a daily voter hash also rejects duplicate votes from the same visitor.

Blocks Show “Attempt Recovery” or Render Blank

Don’t click Attempt Recovery on InnerBlocks blocks. On older content, inner content saved as raw HTML makes the editor flag the block as invalid, and recovery rebuilds it from the template default, wiping your content. Since 2.8.0 the plugin self-heals these posts when they open in the editor, and wp acf-blocks repair-content [--dry-run] [--post=<id>] repairs them permanently in the database.

Legacy block names or blank FAQ sections. The Block Migrator & Repair card (Settings > ACF Blocks License) scans for blocks saved under retired names (acf/table-of-contents, acf/productbox, acf/accordion-item, and others) plus old accordion field schemas, then migrates them in batches of 30 with per-post detail. Every change is stored as a revision plus a restore point, and Revert Migration rolls the whole session back. WP-CLI: wp acf-blocks migrate [--limit=<n>] [--dry-run] [--revert] [--discard].

License Issues

Cannot connect to license server. The plugin connects to https://gauravtiwari.org/ for license operations. Firewalls, DNS issues, or server downtime can prevent connection. The plugin uses a 15-second timeout.

License shows as invalid after renewal. The weekly cron job checks license status. To force an immediate re-check, deactivate and reactivate the license from the settings page.

Updates not appearing. Automatic updates only work with a valid license. Verify your license status at Settings > ACF Blocks License. Also try clearing the update transient by visiting Dashboard > Updates and clicking “Check Again”.

Debugging

Enable WordPress debug logging to see registration errors and other diagnostic messages:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

Error messages from block registration, field group loading, and image localization are logged when WP_DEBUG is enabled. Check wp-content/debug.log for entries prefixed with [ACF Blocks].

Quick answers to common questions: