“Purge Cache” button missing / insufficient privileges error

TL;DR

This bug was first introduced in v.2.3.4 and was partially fixed in v.2.3.5. Purge cache button is missing in admin toolbar and Purge entire cache results in insufficient privileges error. This probably only happens in case of wp-cli installation and activation or upgrade.

Symptoms:

• The Purge Cache button is missing from the admin toolbar
• Clicking Purge Entire Cache on the settings page produces: “Sorry, you do not have the necessary privileges to edit these options.”
• Occurs even when logged in as an administrator
• The Nginx Helper settings page itself is accessible (not an authentication issue)
• Affects some sites but not others running the same plugin version

Root cause

Recent versions of nginx-helper introduced a custom WordPress capability named Nginx Helper | Purge cache (a non-standard string with spaces and a pipe character). Both the admin toolbar button and the purge action gate on this capability:

// admin/class-nginx-helper-admin.php
if ( ! current_user_can( 'Nginx Helper | Purge cache' ) ) {
    wp_die( 'Sorry, you do not have the necessary privileges to edit these options.' );
}

The capability is granted to the administrator role only inside the plugin’s activation hook (class-nginx-helper-activator.php). The runtime role-sync method (nginx_helper_update_role_caps) explicitly skips the administrator role — so nothing re-grants it after the initial activation. This was supposed to be fixed in v2.3.5 by adding handle_nginx_helper_upgrade() hooked toupgrader_process_complete to re-run set_user_caps() on plugin update.

However

set_user_caps() contains this guard:

if ( ! current_user_can( 'activate_plugins' ) ) {
    return;
}

When activating via wp plugin activate, there is no authenticated user in context — current_user_can() evaluates against user 0, returns false, and the function returns before ever calling add_cap. Affects both fresh installs and reactivations done via WP-CLI. I have not discovered other possible paths for this to happen, but I did not investigate further after my issue was solved.

Solutions

Currently the cleanest solution is to add the capability directly through wp-cli

wp cap add administrator 'Nginx Helper | Purge cache' 'Nginx Helper | Config'

Alternatively, you can deactivate and reactivate the plugin in the dashboard.

Disclaimer

This report was partially drafted using Claude Sonnet. The bug was discovered while investigating the issue with the help of Claude Opus. Both the investigation and the final output were supervised and edited by a human (me).