Troubleshooting

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.

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.

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 plugin uses three mechanisms to load styles in the editor. If styles are missing:

1. Verify the style path in block.json is correct (e.g. "file:./my-block.css").
2. Verify the CSS file exists in the block directory.
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.

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

Nonce expired. The nonce is generated on page load. If a page has been open for a long time, the nonce may expire. Reloading the page refreshes the nonce.

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 AJAX handler validates that the post ID corresponds to an existing post. Ratings for deleted posts are rejected.

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].

Disclaimer: This site is reader-supported. If you buy through some links, I may earn a small commission at no extra cost to you. I only recommend tools I trust and would use myself. Your support helps keep gauravtiwari.org free and focused on real-world advice. Thanks. - Gaurav Tiwari