11 ms·

On Writing Better Error Messages

25 points by rozenmd 4y ago

j16sdiz 4y ago
<quote> An error message such as Our service is down for maintenance is infinitely better than: Uh-oh! Something went wrong! </quote> Hell. No. "down for maintenance" implies some kind of maintenance is undergoing, which is often not true. User would expect you are aware of the error, working on it. This can be false expectation.
- prerok 4y ago
  It can be a false expectation, but it should not be. I think that when 5xx errors happen the logging/alerting system should notify the developers/support/infra teams. So, somebody should start working on it ASAP, or whatever your SLA target is. It is definitely true, though, that the user can't do anything to fix it. They just have to try again later. All this, of course, assumes that the code is returning proper error codes, which might also be a false assumption :)
  - rozenmd 4y ago
    Yeah, I meant it this way. 5xx means I'm fixing it, right bloody now because I'm getting paged.
textread 4y ago
PostgreSQL documentation has some handy tips on how to write better error messages: https://www.postgresql.org/docs/devel/error-style-guide.html https://www.postgresql.org/docs/devel/error-style-guide.html I wonder if it would be possible to incorporate such rules into my code editor's linter.
pyrolistical 4y ago
Totally agree but I suspect the bad error message people encounter are the generic catch alls. Of course we would spend the time making better error messages within the product/service domain but that is time and money. Hence a trade off in the end. I would categorize bad error messages as product bugs
kqr 4y ago
Pet peeve: developers assuming any 400-range code is user error. Of all the 403s and 404s I've encountered in my life, the vast majority have been the fault of the developers either running bad configurations or not committed to maintaining URLs. Stop blaming the user for mistyping when it's far more likely you accidentally changed a slug or dropped a redirect or deleted content in a migration or changed web server software without deeply verifying every link after that.
- RadiozRadioz 4y ago
  Indeed, it's not a user error, it's a client error.
  - kqr 4y ago
    I don't think client error captures it either. The client requested the content from the correct URL. In most cases, the problem is that the server has forgot which content should be reachable from that URL.
    - Joker_vD 4y ago
      Ugh, no? It's entirely at the server's discretion as to decide which URLs are correct or not and which, if any, content should be reachable from what URL. If the server decided to forget some content, that's his right. A client may think the URL is correct, but the URL's correctness is determined entirely by the server to which URL refers. Heck, that's why the server part of the URL is actually called "authority", for this exact reason.
      - kqr 4y ago
        A URL is not an alias or directions to some place. A URL is an identifier. Identifiers and the thing being identified are supposed to be permanently linked together. It's the webmaster's responsibility to pick an identifier they think they are able to maintain in perpetuity -- anything else goes against the expectations the web is built on (permalinks, bookmarks, writing down the URL on a post-it, etc.)
layer8 4y ago
Great advice, except for: > Explicitly focus on "we" when the error is caused by an issue on your end The “we” language tends to create a distance between the user and the software, emphasizing that the user is at the mercy of an anonymous “we” (who seem to be in numerical superiority, to boot) that are in control of the software instead of the user, who is implied to lack agency in comparison. This can make users feel patronized and pushed into a passive, dependent, and ultimately powerless role. Microsoft is particularly egregious in this, in messages like “We’re setting a few things up for you”, implying the user is not supposed to be in control of what is being set up for them, like they’re a child, and not even deemed worthy to be informed about what specifically is being set up.
- rozenmd 4y ago
  I think you're conflating two different things. In an error message on the Internet, "You broke our server" vs "Our server doesn't know how to respond to your input, our bad" is not a power play, it's a bad error message. Knowing who caused the issue helps the user figure out what to do next. 401/403? Better login/better annoy my boss for access. 5xx? Oh their server's broken, I'll try again later.
  - layer8 4y ago
    There is no need to insert a “we” group here. The user isn’t interested that it is “our” server. The user doesn’t think in terms of there being people behind the service. He/she is using the service, period. Introducing a group of other people only sets up an inappropriate social dynamics. It feels like the developers are self-inserting themselves into an interaction that is really only between the user and the service. Imagine you are using a ticket machine at the train station, the machine happens to malfunction, and it displays “sorry, our ticket machine is broken”. That is just weird, because the user is only interacting with the ticket machine, not with people operating the machine. It’s not like you’re at the restaurant and the waiter is saying “sorry, our credit card terminal is broken” (which would be an appropriate situation to say something like that). Rather, the ticket machine should display something along the lines of “System malfunction, please retry after pressing the red button. Apologies for the inconvenience.” And similar in the case of a server software.
numlock86 4y ago
I loved early 2000 error messages when PHP scripts would tell you on which column and in which table exactly a MySQL query did fail on public websites ... for, uhm, reasons. :^)
- Skeime 4y ago
  I think even back then, the reason was a poorly configured script running in (essentially) debug mode. You could turn off detailed error messages even back then. Having debug mode be the default was certainly an interesting decision (probably to make things easier for beginners).
nubinetwork 4y ago
> (Airbnb) They tell users there's definitely an issue, and they're working on it But the website doesn't know that... just because I got a 500 doesn't mean anyone knows or cares.
- rozenmd 4y ago
  In large tech orgs, 5xx means (or at least in the ones I've worked at) I'm fixing it, right bloody now because I'm getting paged.
Mizoguchi 4y ago
"Depending on the type of service you run, you'll likely still need request IDs and other diagnostics in your error message to help your support staff debug the issue." Just don't get too carried away here. A few days ago when using one of the USCIS websites I came across a full stack trace including db table names and file paths.
- HdS84 4y ago
  And? Even if so, you should be unable to gain anything from that. As a developer, I am annoyed that we remove so much valuable info from exceptions. It would be better to include more info and then make it easier to dump this information into a logging tool, while the user gets a nice "d'oh" page.
  - JodieBenitez 4y ago
    Ditto... as a developer, I am annoyed by developers printing stack traces in a web page in the first place. These things belong to an error log.
- rozenmd 4y ago
  100% agree - A single ID should be enough anyway, like Cloudflare's Ray ID: https://developers.cloudflare.com/fundamentals/get-started/reference/cloudflare-ray-id/ https://developers.cloudflare.com/fundamentals/get-started/r...

25 points by rozenmd 4y ago

<quote> An error message such as Our service is down for maintenance is infinitely better than: Uh-oh! Something went wrong! </quote> Hell. No. "down for maintenance" implies some kind of maintenance is undergoing, which is often not true. User would expect you are aware of the error, working on it. This can be false expectation.

prerok 4y ago
It can be a false expectation, but it should not be. I think that when 5xx errors happen the logging/alerting system should notify the developers/support/infra teams. So, somebody should start working on it ASAP, or whatever your SLA target is. It is definitely true, though, that the user can't do anything to fix it. They just have to try again later. All this, of course, assumes that the code is returning proper error codes, which might also be a false assumption :)
- rozenmd 4y ago
  Yeah, I meant it this way. 5xx means I'm fixing it, right bloody now because I'm getting paged.

textread 4y ago

PostgreSQL documentation has some handy tips on how to write better error messages: https://www.postgresql.org/docs/devel/error-style-guide.html https://www.postgresql.org/docs/devel/error-style-guide.html I wonder if it would be possible to incorporate such rules into my code editor's linter.

pyrolistical 4y ago

Totally agree but I suspect the bad error message people encounter are the generic catch alls. Of course we would spend the time making better error messages within the product/service domain but that is time and money. Hence a trade off in the end. I would categorize bad error messages as product bugs

kqr 4y ago

Pet peeve: developers assuming any 400-range code is user error. Of all the 403s and 404s I've encountered in my life, the vast majority have been the fault of the developers either running bad configurations or not committed to maintaining URLs. Stop blaming the user for mistyping when it's far more likely you accidentally changed a slug or dropped a redirect or deleted content in a migration or changed web server software without deeply verifying every link after that.

RadiozRadioz 4y ago
Indeed, it's not a user error, it's a client error.
- kqr 4y ago
  I don't think client error captures it either. The client requested the content from the correct URL. In most cases, the problem is that the server has forgot which content should be reachable from that URL.
  - Joker_vD 4y ago
    Ugh, no? It's entirely at the server's discretion as to decide which URLs are correct or not and which, if any, content should be reachable from what URL. If the server decided to forget some content, that's his right. A client may think the URL is correct, but the URL's correctness is determined entirely by the server to which URL refers. Heck, that's why the server part of the URL is actually called "authority", for this exact reason.
    - kqr 4y ago
      A URL is not an alias or directions to some place. A URL is an identifier. Identifiers and the thing being identified are supposed to be permanently linked together. It's the webmaster's responsibility to pick an identifier they think they are able to maintain in perpetuity -- anything else goes against the expectations the web is built on (permalinks, bookmarks, writing down the URL on a post-it, etc.)

layer8 4y ago

Great advice, except for: > Explicitly focus on "we" when the error is caused by an issue on your end The “we” language tends to create a distance between the user and the software, emphasizing that the user is at the mercy of an anonymous “we” (who seem to be in numerical superiority, to boot) that are in control of the software instead of the user, who is implied to lack agency in comparison. This can make users feel patronized and pushed into a passive, dependent, and ultimately powerless role. Microsoft is particularly egregious in this, in messages like “We’re setting a few things up for you”, implying the user is not supposed to be in control of what is being set up for them, like they’re a child, and not even deemed worthy to be informed about what specifically is being set up.

rozenmd 4y ago
I think you're conflating two different things. In an error message on the Internet, "You broke our server" vs "Our server doesn't know how to respond to your input, our bad" is not a power play, it's a bad error message. Knowing who caused the issue helps the user figure out what to do next. 401/403? Better login/better annoy my boss for access. 5xx? Oh their server's broken, I'll try again later.
- layer8 4y ago
  There is no need to insert a “we” group here. The user isn’t interested that it is “our” server. The user doesn’t think in terms of there being people behind the service. He/she is using the service, period. Introducing a group of other people only sets up an inappropriate social dynamics. It feels like the developers are self-inserting themselves into an interaction that is really only between the user and the service. Imagine you are using a ticket machine at the train station, the machine happens to malfunction, and it displays “sorry, our ticket machine is broken”. That is just weird, because the user is only interacting with the ticket machine, not with people operating the machine. It’s not like you’re at the restaurant and the waiter is saying “sorry, our credit card terminal is broken” (which would be an appropriate situation to say something like that). Rather, the ticket machine should display something along the lines of “System malfunction, please retry after pressing the red button. Apologies for the inconvenience.” And similar in the case of a server software.

numlock86 4y ago

I loved early 2000 error messages when PHP scripts would tell you on which column and in which table exactly a MySQL query did fail on public websites ... for, uhm, reasons. :^)

Skeime 4y ago
I think even back then, the reason was a poorly configured script running in (essentially) debug mode. You could turn off detailed error messages even back then. Having debug mode be the default was certainly an interesting decision (probably to make things easier for beginners).

nubinetwork 4y ago

> (Airbnb) They tell users there's definitely an issue, and they're working on it But the website doesn't know that... just because I got a 500 doesn't mean anyone knows or cares.

rozenmd 4y ago
In large tech orgs, 5xx means (or at least in the ones I've worked at) I'm fixing it, right bloody now because I'm getting paged.

Mizoguchi 4y ago

"Depending on the type of service you run, you'll likely still need request IDs and other diagnostics in your error message to help your support staff debug the issue." Just don't get too carried away here. A few days ago when using one of the USCIS websites I came across a full stack trace including db table names and file paths.

HdS84 4y ago
And? Even if so, you should be unable to gain anything from that. As a developer, I am annoyed that we remove so much valuable info from exceptions. It would be better to include more info and then make it easier to dump this information into a logging tool, while the user gets a nice "d'oh" page.
- JodieBenitez 4y ago
  Ditto... as a developer, I am annoyed by developers printing stack traces in a web page in the first place. These things belong to an error log.
rozenmd 4y ago
100% agree - A single ID should be enough anyway, like Cloudflare's Ray ID: https://developers.cloudflare.com/fundamentals/get-started/reference/cloudflare-ray-id/ https://developers.cloudflare.com/fundamentals/get-started/r...