Fixing the 'pll_custom_flag' Function Not Found Error in Polylang

A common and disruptive error that some users encounter with the Polylang plugin is a fatal error stating that the function pll_custom_flag is not found. This error typically appears when trying to add a new post or navigate certain parts of the WordPress admin area, and it prevents the site from loading correctly. Based on community reports, this guide will explain why this error occurs and provide the most effective solutions.

Understanding the Error

The error message usually looks like this:

Fatal error: Uncaught TypeError: call_user_func_array(): Argument #1 ($callback) must be a valid callback, function “pll_custom_flag” not found or invalid function name in .../wp-includes/class-wp-hook.php:308

This is a PHP error that happens when a custom filter for modifying Polylang's flags has been added to the site (often in the theme's functions.php file or a custom plugin) but is incorrectly implemented. The filter hook 'pll_custom_flag' is being called, but the corresponding function it's trying to execute cannot be found.

Why This Error Happens

The primary cause is a conflict or incorrect code snippet. Users often add custom code to change the default flags for their languages, following tutorials from various sources. The error arises if:

• The custom function's name does not exactly match the callback name used in the add_filter function.
• The code is placed in a location where it executes too early, before the Polylang plugin has fully loaded its functions.
• There is a typo or syntax error in the custom code.
• Simple downgrading of the Polylang plugin does not resolve the issue because the root cause is the custom code on the site, not the plugin itself.

How to Fix the 'pll_custom_flag' Error

Solution 1: Check for Code Conflicts

The most likely culprit is custom code in your theme's functions.php file or a custom site-specific plugin. Look for code that uses the pll_custom_flag filter. A typical example looks like this:

add_filter( 'pll_custom_flag', 'pll_custom_flag', 10, 2 );
function pll_custom_flag( $flag, $code ) {
    $flag['url'] = "https://myurl/wp-content/polylang/pl_PL.svg";
    $flag['width'] = 18;
    $flag['height'] = 12;
    return $flag;
}

Action to take: Temporarily disable this code by removing it or commenting it out. If the error disappears, you have confirmed the source of the problem. The next step is to fix the code itself.

Solution 2: Correct the Function Name (Most Common Fix)

A very common mistake is using the function name pll_custom_flag, which is identical to the filter name. This can cause a conflict. The Polylang team recommends using a unique function name to avoid this issue.

Incorrect:

add_filter( 'pll_custom_flag', 'pll_custom_flag', 10, 2 ); // Function name SAME as filter
function pll_custom_flag( $flag, $code ) {
    ...
}

Correct:

add_filter( 'pll_custom_flag', 'my_pll_custom_flag', 10, 2 ); // Unique function name
function my_pll_custom_flag( $flag, $code ) {
    $flag['url'] = content_url("/") . "/polylang/{$code}.svg";
    $flag['width'] = 120;
    $flag['height'] = 80;
    return $flag;
}

Simply changing the function name and the corresponding callback in the add_filter line is often enough to resolve the fatal error.

Solution 3: Ensure Proper Loading Order

Your custom function must be available when Polylang tries to execute the filter. Wrapping your code in a function that hooks into plugins_loaded or after_setup_theme can ensure it loads at the right time.

function my_custom_polylang_flags() {
    add_filter( 'pll_custom_flag', 'my_pll_custom_flag', 10, 2 );
    function my_pll_custom_flag( $flag, $code ) {
        // Your custom flag code here
    }
}
add_action( 'plugins_loaded', 'my_custom_polylang_flags' );

Solution 4: Check File Paths and Caching

If your error is resolved but your custom flags still don't appear, verify the file path in your function's $flag['url'] line. Ensure the image files (e.g., en.svg, fr.svg) actually exist in the wp-content/polylang/ directory. After making any changes, clear your site's cache (both any caching plugins and your browser cache) to see the changes.

Conclusion

The pll_custom_flag not found error is almost always caused by a conflict with custom code on your site, not a bug in the Polylang plugin. By carefully checking your custom flag code, ensuring you use a unique function name, and verifying the loading order, you can resolve this issue and successfully use custom flags with Polylang.