Regardless of your level of experience with WordPress, everyone is familiar with seeing the messages that display whenever an action has completed within the dashboard:

  • We have success messages for when something has completed, ahem, successfully,
  • We have notification messages which are neutral pieces of information that give a heads up something has happened,
  • And we have error messages that let us know that something has gone wrong.

For anyone that’s read past articles, you know that when it comes to introducing functionality into the WordPress dashboard, I firmly believe that the work we do should look as native as possible. That is to say that I am not a fan of custom styles, custom controls, or extraordinary styles to give your theme or plugin that “extra edge.”

And for those who are familiar with the Settings API and/or the Options API, then you’re likely familiar with introducing new sections, settings, controls, and options, but what about error messages?

Display Error Messages in WordPress

Generally speaking, success messages and notification messages are reasonably easy to come by, but let’s say that you need to validate some piece of information that’s coming into the server and return an error if it fails.

Display Error Messages in WordPress

As with most things, things like this are usually best demonstrated through a practical example. Luckily, there’s no too much to setup before we take a look at how to do it.

So let’s assume the following:

  • We have a meta box on the post dashboard
  • The meta box contains an input box
  • When the post is saved, the input box cannot be empty (I know, that’s a bit extreme, but it’ll demonstrate the point)
  • If the input box is empty, then we’ll display an error message

Easy enough, but in order to save time, I’m going to assume you’re familiar with the add_meta_boxes action, the add_meta_box function, the save_post hook and how to validate data from within the hooked function.

In this case, we’re going to be making sure that the data coming in from the meta box input is not empty. If it is, then we’ll display a native WordPress error message.

To that end, let’s assume that the input box has the name attribute of acme-input-field and it can be accessed via the $_POST collection by retrieving it as $_POST['acme-input-field'].

From there, let’s do something like the following:

Notice that in the above function, the majority of the work is checking that the user has permission to save the data and the the incoming information is not empty. If it is empty, then we make a call to add_settings_error.

According to the Codex, this function:

Use this to show messages to users about settings validation problems, missing settings or anything else.

This is exactly what we’re aiming for when wanting to displaying a natively styled error message, isn’t it?

Lastly, if you’re curious about the second parameter and as to why I left it an empty string, it’s because the default parameter is an empty string, but is used for this:

Slug-name to identify the error. Used as part of ‘id’ attribute in HTML output. A prefix of ‘setting-error-‘ will be added to the string in $code and assigned to the ‘id’ attribute of the outermost <div> for this error.

For all intents an purposes of this particular example, this wasn’t needed, but if you’re looking to gain access to this message via CSS or JavaScript, or are looking to make sure every element has proper semantics, then I highly recommend using it.


Join the conversation! 17 Comments

  1. Nice example. I have always done these very manually using the admin_notices hook. Probably the old way to accomplish it.

    This function is much better.


    • The are definitely times when that hook works and is necessary, but if you’re working with the Settings API or are looking to have a much easier time with hooking into the native functionality (and styles), this is a much easier route.

  2. Nice article. I always wandered if there was a similar way to throw an error in the front end.
    This could be useful for alerts, like, say, for a form validation.
    I guess it could be done with a new WP_Error instance, but I never really figured out how to do it in practice.
    Any ideas?

    • There are ways to throw errors on the front end, though I can’t speak for certain that WP_Error would be the right choice. It might be, I’ve just never used it that way.

      Generally speaking, I’d look at generating the error on the server side and then keeping it in some type of collection or globally accessible object that can be retrieved from both the frontend and the backend.

      I’m almost positive there’s a mechanism for this, but the proper (or best practice way of doing it) is escaping me at the moment.

  3. Thanks for the article, I tried to make the same thing for my metabox but nothing happend can yougive full example? Should I use get_settings_errors and loop through theme to diplay errors??

  4. Hello, nice article! However not all is clear for me(I’m newbie in WP so maybe this is the reason :)). Where should I put this code? I mean hook save_post? Because I have from and after clicking I wnat to run your code – my question is how? Please answer if possible.

    • If you’re using a class, then this would exist within the context of the class, but the save_post hook would live wherever you defined the rest of your hooks.

      As I mentioned in the post:

      Easy enough, but in order to save time, I’m going to assume you’re familiar with the add_meta_boxes action, the add_meta_box function, the save_post hook and how to validate data from within the hooked function.

      So it’s very likely that you’re just dropped this in functions.php or in the plugin file’s root. Either one of those would be fine, but it should intercept the input form based on what the code has (and that your inputs are properly being set in on the form elements).

  5. Of course form, not from :)

  6. Hi Tom,

    Nice trick here but I can’t seem to make it work.

    I’ve added the setting_error within my ‘save_post’ hook. But It seems to be lost afterwards. I can’t display the error, it doesn’t appear to be present in the ‘get_settings_errors()’ returned value.

    Any Idea ? Here’s a pastebin to illustrate.

    • After taking a quick glance at your code, everything seems okay. Have you taken a look into the database to see if the message is being serialized to the proper table, or have you tried getting the settings error using the API to first test that out before letting core automate the process?

  7. Yes I tried all sort of things, the settings error doesn’t seem to be saved in the database.

    I even tried to save the transient myself like this :

    add_settings_error( ‘mandatory-field’, ”, __( ‘You must define a value in the metabox.’, ‘acme’ ), ‘error’ );

    set_transient( ‘settings_errors’, get_settings_errors(), 30 );

    This does save the value, but it’s not catched by get_settings_errors() afterwards anyway…

    • When you use the code that’s provided in the gist above and set breakpoints or or try any var_dumps, are those breakpoints hit?

      I’m wondering if the hook is actually even being fired.

  8. Hi,

    I checked with var_dumps and the hook is fired properly.

    The issue is in the get_settings_errors() function. It checks for a $_GET[‘settings-updated’] that isn’t set when the admin hits the update button from a post. (See there ).

    It works if I add this filter :

    Anyway, it’s bothering me to use a filter in addition to a native functionnality. What do you think ?

    • Unfortunately, without taking a deeper look at the surrounding code, I’m honestly not sure what else to offer aside from continuing to debug it line by line.

      Wish I could be more help!

  9. Thanks for having tried :)

    At least this made me discover these native functionalities that I’ll use on my custom settings pages from now on.

Leave a Reply