Back to Community
Home / Community / Plugin → Advanced custom fields (acf®)

Understanding and Fixing ACF's Unsafe HTML Escaping Notices

22 threads Sep 9, 2025 Plugin → Advanced custom fields (acf®)

Content

If you've recently updated the Advanced Custom Fields (ACF) plugin, you may have encountered a new and confusing notification in your WordPress dashboard. This article will explain what these notices mean, why they were introduced, and provide the most common solutions to resolve them.

The Problem: New ACF Security Notices

Starting with ACF version 6.2.5, the plugin began displaying warnings about "escaping unsafe HTML." The messages typically look like this:

  • Warning (Pre-6.2.7): "ACF will soon escape unsafe HTML that is rendered by the_field(). We've detected the output of some of your fields will be modified by this change."
  • Notice (Post-6.2.7): "ACF now automatically escapes unsafe HTML when rendered by the_field or the ACF shortcode. We've detected the output of some of your fields has been modified by this change, but this may not be a breaking change."

These alerts list specific field names and the template functions used to display them (e.g., the_field(), the_sub_field(), or [acf] shortcode).

Why This Change Happened

The 'Advanced Custom Fields (ACF®)' team implemented this change as a critical security enhancement. The goal is to prevent Cross-Site Scripting (XSS) attacks by automatically escaping potentially harmful HTML code before it is output on your site. This is a WordPress best practice that helps protect your site if a user with editing permissions adds malicious scripts to a field.

Common Symptoms and Issues

While this is a security improvement, it can sometimes alter the intended output of your fields. Users have reported several specific issues, including:

  • Embedded iframes (e.g., Spotify players, tweets, YouTube videos) within WYSIWYG fields no longer display.
  • Custom HTML, scripts, or shortcodes in textarea fields are rendered as plain text instead of being executed.
  • The admin notice persists even after addressing the underlying issue.

How to Fix It: Recommended Solutions

Here are the most common and recommended approaches to resolve these notices and restore functionality.

1. Manually Escape Output in Your Theme (Recommended)

The most secure and future-proof method is to update your theme's template files. Replace functions that automatically echo output with functions that return a value, and then escape it appropriately for its context.

Instead of:

<?php the_field('my_unsafe_field'); ?>
<?php the_sub_field('my_unsafe_field'); ?>

Use:

<?php echo wp_kses_post( get_field('my_unsafe_field') ); ?>
<?php echo wp_kses_post( get_sub_field('my_unsafe_field') ); ?>

The wp_kses_post() function allows the same HTML tags permitted in standard WordPress posts. For more specific control, use other escaping functions like esc_url() for links or esc_html() for plain text.

2. Allow Specific HTML for a Field via a Filter

If you fully trust the content of a specific field and need to allow HTML, you can use a filter. Warning: Only use this if you trust all users who have permission to edit the field.

Add the following code to your theme's functions.php file, replacing 'your_field_name' with the actual name of your field.

add_filter( 'acf/shortcode/allow_unsafe_html', function ( $allowed, $atts ) {
    if ( $atts['field'] === 'your_field_name' ) {
        return true;
    }
    return $allowed;
}, 10, 2 );

3. Allow "Unsafe" HTML Everywhere (Not Recommended)

As a last resort for sites where you are the sole trusted user, you can disable the escaping globally. This severely reduces your site's security and is not recommended for most sites.

add_filter( 'acf/shortcode/allow_unsafe_html', function ( $allowed, $atts ) {
    return true;
}, 10, 2 );

What If It's Not a Breaking Change?

If you've confirmed that the escaping did not break anything on your front end, the notice might just be informational. Currently, the log that triggers this notice can be stored in your database. The notice will continue to appear as long as this log exists. Some users have requested a way to dismiss the notice permanently in this scenario, but a built-in method is not currently available.

Final Thoughts

While the initial rollout of this security feature caused confusion, it is an important step in securing WordPress websites. The recommended path is to audit your fields and update your theme templates to escape data properly. This approach aligns with WordPress coding standards and provides the strongest security for your site.

For further reading, the 'Advanced Custom Fields (ACF®)' team has published a resource on HTML escaping.

Related Support Threads Support