Error messages should indicate why the error occurred such that the user can address the problem to avoid the error.

Registered by Victoria Kouyoumjian on 2014-01-02

Error messages can come from different sources (API, internal, framework), but we are currently catching all the exceptions and return a generic and sometime misleading message to the user. This blueprint suggest to normalize the API exception handling. To do this, we need to standardize how exceptions messages are generated.

exception_msg(request, msg_template, context)

Refactor horizon.exceptions.handle. The initial design is still valid. Dividing the exceptions into categories still makes sense. The list of categories can be generated automatically according to the API's exception list and provide a list of excluding exceptions. This is less error prone and easier to manage.

Either a API wrapper function or an view decorator can process the exceptions in a uniform manner.


***** 10.28.2016 [clu_] Great history in this patch, but not feasible at this time. Better to update documentation to tell deployers why we *can't* make exceptions better. :o

[akrivoka 2014-02-03]
Note that propagating the exception message to the user is not an acceptable solution to this problem. For more details and further discussion on this topic, check out the related bugs list and this mailing list discussion:

[peristeri 2014-02-15]
I agree with akrivoka. Because of the size of the work, I was suggesting of getting the remaining communities to agree to a standard error message format first before begining working on implementing the changes.

[peristeri 2014-02-21]
There's 2 reason we will get a error message. First reason is the actions [call to api] is invalid. The second reason is the account limitations, for which different providers would want to handle the situation according to their business rules.

One suggestion is to implement a plug-in system to override the message template according to the exception raised. The benefits are the cloud provider can customize the layout and the message of the error message.

To implement this form of plug-in, the exceptions raised will need to contain the messages that can be overridden. By default it would be the message type and the resolution message.

Gerrit topic:,topic:bp/improve-error-message-details-for-usability,n,z

Addressed by:
    Better error message handling

[amotoki 2014-04-07]
During bug triage, I have several bug reports on error message (in neutron part).
Several numbers of Exceptions from Neutron contains UUID and it is not good from UX perspecitve. On the other hand, the status code is not enough for detail message handling. At least we need to know an original exception type to display appropriate error messages.
It seems better to deal with this blueprint with client libraries. I have a plan to work on this in neutronclient in Juno to report neutron exception type in exception classes and Horizon can display appropriate message. For example, bug 1279485 we can display a good message if we know the exception comes from NetworkInUse.

[lblanchard 2014-05-29] I've put together a proposal around the UI guidelines for Error Messaging that would be great for Horizon. This doesn't call out any technical details, but it points towards consistency of messages no matter which component owns surfacing the message. Please take a look and give feedback if you can!

[jpichon 2014.06.25] The associated patch is abandoned, what's the current status on this? If there is work about this going in the other services like amotoki mentions, could we perhaps link to it here?

Maybe we could pursue option #3 in for now, even just showing the exception error class name like OverQuotaException() or whatever. It is not at all the nicest user experience but it's miles ahead of "generic error occurred, try again later" that leaves the user stranded and trying to reproduce the operation on CLI so that they can get more useful information. I don't think there's any risk in exposing these messages because a end-user would already see them when using the CLI tools.

Some services have also started adding a Accept-Language header that would let us get translated message which we should look into using - of course until the translation team capacity grows enough to be able to encompass other services this may not be as helpful.

I'm happy to help with this work, just trying to figure out where we're at. Thanks!
Also thanks Liz for the document you linked to, it's excellent food for thought and I think we'll want to make the tips for writing good/human-readable error messages visible to folks working on the other services as well.

[david-lyle | 2014.07.02] I'm wondering if for a stop gap solution we start with the generic error message that is translated. Like "Attempt to do X failed." Then provide an expander/dropdown and show the untranslated message in the exception when that expander is opened. This at least give non-English users a string to google translate or google. It's not very elegant, but more informative than nothing.

[mrunge | 2014.07.03] I thought in a different direction: Shouldn't we try to improve openstack clients to throw the "right" exception for us to catch?

E.g. when launching an instance with a volume you could have
- Volume Quota exceeded
- CPU Volume exceeded (still Horizon tries to prevent this in launch dialogue)
- disk full on volume host
- disk full on compute node
- all kinds of networking issues, timeouts etc.

Those exceptions would carry meta information to pass to the user, they would be easily translatable, and we can control, what kind of info goes to the end user.

Downside of this approach is: it would introduce a lot of new exceptions to be thrown and catched, if they really don't exist yet. At least, that would require tons of work.

[jpichon 2014.07.03] David, that sounds reasonable to me for a start. I think any improvement sounds reasonable for a start, we keep getting more and more bugs about this because this is a problem for everyone. We need some stop-gaps in place until the Perfect Solution, whatever it is, is finally available (that one likely requires client work indeed).

Matthias, I believe a number of clients already provide more specific exceptions (that extend the generic exception that we do catch), perhaps that can help to also provide a specific stop-gap in several places.

George, are you still working on this?

[peristeri 2014.07.03] Yes, I'm still working on it jpichon, I was distracted this past month. I will be submitting a prototype next week that follow David's suggestion.

[jpichon 2014.07.04] Awesome, thank you!!

[robcresswell 2015.03.26] Hey George, are there plans to carry this one past the exceptions list refactoring? I'm keen to help out, and wondered if there was a solid plan going forward; I'd really like to drive this in Liberty. Could we sync up on irc or hangouts? Cheers.

[peristeri 2015.03.26] Hi Rob. Yes, I still working on it. I was about to submit a POC but realized that it did
not handle cases where there's multiple exceptions raised by the API call. How about we organize a hangout on Monday (30th March)?

Addressed by:
    [WIP] Standardize the exception handling thrown by services.

Gerrit topic:,topic:refactor-handler,n,z

Addressed by:
    Refactoring the exceptions lists

Addressed by:
    Removed the '_safe_message' variable from the API exceptions

Addressed by:
    Refactoring the exceptions lists

[peristeri 2015.05.27] I want to bring to the attention the presentation It brings out the biggest problem with exceptions. The errors are misleading.


Work Items