Have you encountered the error Please provide a custom field value after attempting to save a custom field in WordPress that has a non-blank value?

WordPress gives this error even when you specify a value for your custom field/post meta, which is misleading. When does this happen, and why? The short answer for the exact cause examined here is due to protected meta keys. It takes a bit of source code traversal to unravel this mystery.

This behavior is defined in the file /wp-admin/includes/ajax-actions.php as part of the function wp_ajax_add_meta.

The error is specified in several places within the function definition – including where its placement is expected, such as when a trimmed meta value is an empty string:

if ( '' == trim($value) )
	wp_die( __( 'Please provide a custom field value.' ) );

The real culprit is buried behind the add_meta function, which also fires the error message upon failure to save the meta.

if ( !$mid = add_meta( $pid ) )
	wp_die( __( 'Please provide a custom field value.' ) );

In the add_meta function definition in /wp-admin/includes/post.php, you’ll see this block:

if ( is_protected_meta( $metakey, 'post' ) || ! current_user_can( 'add_post_meta', $post_ID, $metakey ) )
	return false;

A quick glance at the is_protected_meta definition inside /wp-includes/meta.php, and you’ll see the real cause:

$protected = ( '_' == $meta_key[0] );

If you’re using a meta key prefixed with an underscore, you are prevented from specifying it via the WordPress post editor’s Custom Fields section (added/removed from your editor via the Screen Options button).

Fortunately, most users don’t tend to manage custom fields directly, nor are they likely to prefix their meta keys with underscores. So since this problem is most likely to be encountered by a developer, there is a workaround available:

The is_protected_meta function passes its return value through the filter is_protected_meta filter, providing the extra parameters meta_key and meta_type. While it may not be great to rely upon it as you may forget it is not core behavior, you can add a filter that allows your fields to be managed via the post editor.

Note that this error is not likely to be encountered since normally protected meta are managed programmatically. The post editor is a convenient way to update or add meta and can be helpful for debugging purposes. If you happen to decide to filter protected meta protection, consider restricting any exceptions by user, capabilities, or roles to avoid letting novice users break protected fields by inadvertently using invalid or unintended meta values or changes.