Custom WordPress Plugin Activation Error Messages

One of the goals of being a WordPress Plugin developer is to reduce the amount of support needed by people using your plugin. One way to make your life easier is to display easy to understand error messages when something about their setup is preventing your plugin from working correctly. One way to do this is to check for compatibility during the plugin activation. Unfortunately, by default when WordPress fails to activate your plugin only cryptic or unhelpful messages are typically displayed. I will introduce a quick and easy way around this.

To add code that runs during activation you simply add the following line to your plugin:


where your_activation_function is the name of some function in your code that handles your plugin activation.


By default WordPress will display one of two error messages if your plugin fails to activate:


  1. The plugin generated %d characters of unexpected output during activation. You will see this is you have any text outside of the <?php ?> tags in your plugin’s php files, or try to output any information during the activation process. You cannot simply output error messages during activation, because WordPress will not show them.
  2. Plugin could not be activated because it triggered a fatal error. If your plugin triggers an error during the activation, this message is shown in addition to the php output error message. If you have a custom error handler setup on your server then this detailed error information may appear elsewhere.

Neither of these error messages are very helpful; fortunately, this behavior can be modified.  When WordPress activates plugins it first validates the header information of the plugin, and then it loads the plugin and runs the activation hook. If it detects any errors or output it decides the plugin is broken. It then opens up an iFrame where it runs the plugin activate hook a second time. When it does this WordPress adds a url parameter so we can know where in the activation process we are. So, instead of using the built in trigger_error function you can define your own that modifies the behavior according to the whether or not the action=error_scrape parameter is present.

Instead of

trigger_error('Some error message', E_USER_ERROR);


br_trigger_error('Some error message', E_USER_ERROR);
function br_trigger_error($message, $errno) {
          &amp;&amp; $_GET['action'] == 'error_scrape') {
        echo '<strong>' . $message . '</strong>';
    } else {
        trigger_error($message, $errno);

Your users will now be presented with information that they will be able to understand.

As an example, one of my plugins uses file_get_contents to retrieve information from a url, which requires that allow_url_fopen is allowed. In the activation function I have:

  if(!ini_set('allow_url_fopen')) {
    br_trigger_error('Your server does not allow \'allow_url_fopen.\' Please contact your webmaster and ask them to enable this setting.');

6 thoughts on “Custom WordPress Plugin Activation Error Messages

  1. Thank you for posting this!
    However, I would like to use this code. It seems almost too simple to even copyright, but I would like to play it safe.
    What license is this code released under?
    If it’s too restrictive, I’ll have to seek an alternative source.


  2. Instead of all of this, you could simply use die(‘Your error message here’) and avoid the extra complication. On the second plugin load, where WordPress scrapes for the error message, you could still search for error_scrape and not duplicate the failed plugin activation and print out the error message directly.

  3. Is there a way to prevent these messages from disappearing after a few seconds so they can be analyzed? Or are they logged somewhere?

Leave a Reply to jason Cancel reply

