Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Write better error messages

wix-ux.com

Post reply on HN
Print view View original

101–110 of 265 posts

Re: Write better error messages

#101

Post by alisonatwork »

marklubi wrote: post #87
nkrisc wrote: post #82

Earlier quoted context omitted.

The goal of writing better error messages isn't to help the people who never read error messages, it's to help the people who do and who you never have to hear from.

The trick that I've found is that each error message needs to be unique... not just the stack trace, but the actual wording of the message leading up to that. Get a screenshot or the exact verbatim of it, and you can identify exactly where in the code it originated. User reports are unreliable, but when I can pinpoint where the message originated from, it massively cuts down on the troubleshooting time.

A useful thing here is not just to include a unique error code for the type of error (usually numeric), but also to generate some kind of short Base32 or similar hash and print that right next to the error message while logging it to your normal back end. Then whether people send you a screen shot, copy/paste, whatever, you can easily search the logs to find the exact event that occurred.

Re: Write better error messages

#102

Post by thenerdhead »

As with everything, context matters. It's a great run-down of how to empower an error message. Many products can add so much value and saved support resources by doing so.

There's one thing I wasn't sure about in this article though. Did they talk to actual users regarding these empowered error messages or even asked them what they want to see out of common error messages they run into? It seems rather difficult to empower error messages without first understanding the scenarios that got them into the error state to begin with. Next would be understanding if these error messages are helpful to the users and asking them how they go about resolving these types of issues. All of that is hinted at in the "what makes a good error message".

Re: Write better error messages

#103

Post by 0xbadcafebee »

hprotagonist wrote: post #3

I would, if i had any evidence at all that they would be read and acted on. I’m convinced even seemingly competent people are just rendered contextually blind by the appearance of any error at all. In the past month, i’ve had about a dozen interactions like this: developer: your service crashed, here’s a screenshot of the last 5 lines of the crash me: do you see where the final text you just pasted is “RuntimeError:…

The problem is here: "RuntimeError:". Once they saw that, they stopped reading. "Did not find ENVVAR" [..] "ensure this is set to the proper value" [..] "and then restart the service" are also obscure and will stop them from reading.

Why is the user like this? Error message PTSD. Years of staring at obscure errors full of technical jargon that are not helpful to the user, has left them scared to even look at the content of the error message. They have tried to Google these things before and failed, and now they just avoid it entirely and run for help.

I'm sure there's enough detail in the link you provided to help the user. But if that's the case, it will be better for the error message to simply say:

  A problem occurred, but don't worry! You can fix it yourself in 5 minutes! For instructions, visit https://internal-wiki-link/spaces/BLAH/AppUserRuntimeError#A013579
Even if you expect the user to be "smart enough" to fix their own problem, they are more likely to try it themselves if you make it seem easier.

Re: Write better error messages

#104

Post by AlwaysRock »

hprotagonist wrote: post #3

I would, if i had any evidence at all that they would be read and acted on. I’m convinced even seemingly competent people are just rendered contextually blind by the appearance of any error at all. In the past month, i’ve had about a dozen interactions like this: developer: your service crashed, here’s a screenshot of the last 5 lines of the crash me: do you see where the final text you just pasted is “RuntimeError:…

It's a little annoying but to be fair because most error messaging is garbage, its easy to start to ignore them. How often is the error message shown, and the little fix given, actually going to solve the problem in modern web development? 10% of the time? 25% of the time? I'd be shocked if its that high.

Re: Write better error messages

#105

Post by 0xbadcafebee »

mariusmg wrote: post #17
zagrebian wrote: post #8

Earlier quoted context omitted.

This just means that the error message needs to be more clear. For example, after the error itself, it could give direct advice: “PERFORM THESE STEPS: You must define ENVVAR. Go to . Set ENVVAR to a proper value and restart the service.” Notice the direct language. It reads like an order. The less direct the message, the higher the chances that the user will not act upon it.

>it could give direct advice: “PERFORM THESE STEPS: You must define ENVVAR. Go to . Set ENVVAR to a proper value and restart the service.” Really, should logs also be documentation now ? Just mindlessly logging the same "advice" over and over again each time the error happen ?

Logs actually are a form of documentation. Documentation can provide instructions on how to diagnose and fix problems, and that's what logs do: tell a human being what a problem is and how to fix it.

Remember that often the person reading the logs is not the person who wrote the software. Maybe it's an Ops person at 2AM trying to fix a broken deploy. Maybe it's a developer who joined the company 3 years after the software was written. Maybe the log is passing through an error message from 3 layers deep in the stack. The more literate your logs are, the better.

Re: Write better error messages

#106

Post by quintussss »

hprotagonist wrote: post #3

I would, if i had any evidence at all that they would be read and acted on. I’m convinced even seemingly competent people are just rendered contextually blind by the appearance of any error at all. In the past month, i’ve had about a dozen interactions like this: developer: your service crashed, here’s a screenshot of the last 5 lines of the crash me: do you see where the final text you just pasted is “RuntimeError:…

Isn't this just survivor bias though? You only hear from those that fail to read and act on the error message.

Re: Write better error messages

#107

Post by [deleted] »

ajnin wrote: post #6
hprotagonist wrote: post #3

I would, if i had any evidence at all that they would be read and acted on. I’m convinced even seemingly competent people are just rendered contextually blind by the appearance of any error at all. In the past month, i’ve had about a dozen interactions like this: developer: your service crashed, here’s a screenshot of the last 5 lines of the crash me: do you see where the final text you just pasted is “RuntimeError:…

How many interactions didn't you have, because the developer read the error message, read the Wiki, and ultimately solved the issue themselves ?

[deleted]

Re: Write better error messages

#108

Post by SpicyLemonZest »

prerok wrote: post #89
dementiapatent wrote: post #23

Earlier quoted context omitted.

It will be so much fun when the implementation is refactored and half of these comments are forgotten about and no longer meaningful.

Exactly. At one of my previous workplaces there was a cumulative effect of misattributed error messages so the actions to perform were often of no help. Not even to mention the fact that new or changed error messages caused a landslide in costs in translations to various languages. I guess this product has no localization? At that time, when I was working at such a product that had it, we had to go through a delibera…

I had an error message a few months ago that instructed me to reinstall the AWS CLI, I filed a ticket when that didn't work, and the team was annoyed with me because obviously the real problem was a Python configuration warning with no suggested action 10 lines up.

Re: Write better error messages

#109

Post by bee_rider »

zagrebian wrote: post #8
hprotagonist wrote: post #3

I would, if i had any evidence at all that they would be read and acted on. I’m convinced even seemingly competent people are just rendered contextually blind by the appearance of any error at all. In the past month, i’ve had about a dozen interactions like this: developer: your service crashed, here’s a screenshot of the last 5 lines of the crash me: do you see where the final text you just pasted is “RuntimeError:…

This just means that the error message needs to be more clear. For example, after the error itself, it could give direct advice: “PERFORM THESE STEPS: You must define ENVVAR. Go to . Set ENVVAR to a proper value and restart the service.” Notice the direct language. It reads like an order. The less direct the message, the higher the chances that the user will not act upon it.

There's a type of error for which the user can be given detailed step-by-step instructions (permission issues, etc). But to some extent, errors should handle situations the programmer didn't expect. If it is possible to provide detailed step-by-step fixes, then the program should do those steps itself.

Adding a URL might not be a great plan, never know how long an old copy of a program will stick around, might not control that website forever.

Post reply on HN