WordPress ACF and field names

Ran into an issue today with the naming of ACF fields.

TL;DR: ACF fields that override native WordPress properties (like description on nav_menu_item) can cause fatal errors in the Customizer. The solution is to delete the conflicting post meta from the database.

Description Bad!

Description is a common name for a field. We need to add it to our menu items because we're working on a mega menu where each menu item has a small description.

We used the field name description thinking nothing of it.

The symptoms

Generally it worked. However, we noticed that in the WP REST response of the menu-items endpoint we were seeing the description in the top level of the menu-item object. That didn't seem right since normally ACF fields should up in the ACF property array.

But it basically worked since the data was there.

Broken Customizer

However, at some point we noticed that the customizer was broken logging the following somewhat misleading error:

HP Fatal error:  Uncaught Exception: Supplied nav_menu_item value missing property: description in /var/mypath/wp-includes/customize/class-wp-customize-nav-menu-item-setting.php:183

From what I can tell, ACF saves the description field as post meta, unintentionally overwriting the native property - which WordPress core still expects to be present when loading the customizer.

Even after we removed the field from ACF it seems as though the post meta entries still persist in the database which cases WordPress to misinterpret the menu item object.

The Fix

Unfortunately to fully resolve the issue you'll need direct database access to remove the leftover description post meta from nav_menu_items posts.

It would be something like this:

DELETE FROM wp_postmeta
WHERE meta_key = 'description'
AND post_id IN (
    SELECT ID FROM wp_posts WHERE post_type = 'nav_menu_item'
);

Best practice going forward

I'm not exactly sure how to know what fields are going to conflict, but I guess saying don't use field names that conflict with native WordPress properties is not too obvious.

For sure don't use description and maybe just be a little creative so as to avoid the obvious.