Carbon Fields plugin review and common issues

Complex field save failures often indicate a PHP error preventing the save routine from completing. Check the WordPress debug log (wp-content/debug.log with WP_DEBUG enabled) for any PHP errors during save. Common issues: (1) a field registration code is throwing an exception — wrap in try/catch during debugging; (2) the Complex field’s entry_separator or index separator conflicts with field data containing the separator character — use unique separator values; (3) a conflicting plugin is modifying the $_POST data before Carbon Fields processes it. Use a JavaScript debugger to verify the form is submitting the Complex field’s serialized data correctly.

Carbon Fields requires manual bootstrapping. The Boot class must be instantiated before defining containers: add_action(“after_setup_theme”, function() { Carbon_FieldsCarbon_Fields::boot(); }); If this action is called too early or too late, the boot fails silently. Also verify: (1) the autoloader is set up correctly — if using Composer, the autoload.php must be included; (2) if using the WordPress.org plugin (not Composer), ensure the plugin is active; (3) check for PHP errors in the error log — a class not found or namespace error will prevent Carbon Fields from loading.

Carbon Fields does not automatically expose field data in REST API responses. To include a field in REST output, register the field with REST API support using the set_visible_in_rest_api(true) method on the field definition: Field::make(“text”, “my_field”, “My Field”)->set_visible_in_rest_api(true). This adds the field to the REST API response for the associated post type. Complex fields (repeatable) require additional configuration — consult the Carbon Fields documentation for REST API serialization of Complex field data.

Use the Container::make(“theme_options”) method to create an options page: Container::make(“theme_options”, “Site Settings”)->add_fields([Field::make(“text”, “crb_phone”, “Phone Number”), Field::make(“image”, “crb_logo”, “Site Logo”)]); This creates a “Site Settings” page in the WordPress admin. Retrieve option values anywhere in your theme using carbon_get_theme_option(“crb_phone”). For sub-pages (nested options pages), chain ->set_page_parent() to the container registration. Options page data is stored in wp_options, not post meta.

Carbon Fields provides a Block field type for custom Gutenberg blocks. Register the block container using Container::make(“block”, “My Custom Block”)->add_fields([…]). Carbon Fields handles the block registration and sidebar field rendering. Create a PHP render callback function that uses carbon_get_block_field(“field_name”) to retrieve block field values and output HTML. This approach creates server-side-rendered Gutenberg blocks with Carbon Fields-managed data inputs without writing React or JavaScript.

For WordPress theme development where fields are defined in the theme and need to be version-controlled with the theme codebase, Carbon Fields and ACF Pro’s JSON sync feature both achieve the same goal. Carbon Fields has zero licensing cost and a slightly cleaner PHP OOP API. ACF Pro has a more extensive community, better page builder integrations, and a backup admin UI for field management. For solo developers or small teams, Carbon Fields’s zero cost and clean API are compelling. For agencies that need to hand off field management to clients, ACF’s admin UI is essential.

Yes — Carbon Fields is explicitly designed for use in both themes and plugins. When used in a plugin, install Carbon Fields as a Composer dependency: composer require htmlburger/carbon-fields. This bundles the library within your plugin without requiring users to install Carbon Fields separately. The Composer approach ensures your plugin is self-contained. Do not assume the WordPress.org plugin version of Carbon Fields is present — always bundle via Composer for plugin distribution.

Yes, that can happen, especially on older sites with many plugins. This usually happens when the plugin, theme, and add-ons are updated out of sequence. In most cases, testing on staging catches the issue before it reaches the live site. From experience, backups and changelog reviews save a lot of cleanup time.

Start by checking whether another plugin already does the same job. In most cases, overlap is what creates avoidable conflicts and performance issues. A common issue is installing a plugin because it looks convenient without checking the stack first. From experience, a short compatibility review avoids most of the pain later.