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

81–90 of 265 posts

Re: Write better error messages

#81

Post by ChrisMarshallNY »

The general approach that I take, is that an error message is one of the most stressful occurrences that a user encounters, so it's incumbent upon me to make it as pain-free as possible.

First of all, unless I'm writing an engineering tool, my users aren't geeks, and don't especially care why the error is happening (geeks always need to know why). They just need to know that what was expected, did not happen. If there is a remedy, and it can be simply stated, then I can add that, but it needs to be short and simple. Longer stuff needs to go into some kind of secondary screen (which probably won't be read).

Also, I take the "shopkeeper" approach. The customer is always right, and it's never the customer's fault. I avoid any hints of blaming the user (even if it is their fault), and try to be polite and helpful[0].

Of course, the best way to deal with errors, is to avoid them. I try to design good affordances.

The rules are different for SDKs, though. In that case, I tend to send a great deal of information back. I take advantage of Swift's enums, and the ability to associate data. It can allow me to nest error reports.

[0] https://littlegreenviper.com/miscellany/the-road-most-travel...

Re: Write better error messages

#82

Post by nkrisc »

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 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.

Re: Write better error messages

#84

Post by riskable »

magicalhippo wrote: post #13

If you're raising an exception deep in some internal code, provide as much detail as possible. If the error bubbles up to the user, then either the information is over their head, in which case there's no difference to a non-detailed error message, or the user/support person can actually act on it. The most infuriating error I see is "file not found"... WHICH FILE?! Of course if the error is found in the higher level…

> If you're raising an exception deep in some internal code, provide as much detail as possible.

> If the error bubbles up to the user,

...then you have an information disclosure vulnerability! There's a really good reason why we don't bubble up deep exceptions to end users: Attackers can use that info to gain information about your back end that they can use to find worse vulnerabilities.

Put all the detail you want in your logs. Keep the end users out of it. They shouldn't be able to tell what line broke things.

Re: Write better error messages

#85

Post by Kalium »

jimmytidey wrote: post #26
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 is a context where people are used to seeing errors that they don't know what to do with. If a web app pops a well written error it is much more likely to be acted on than an unmotivated dev seeing a some (probably badly formatted) text. Every time I see an error in terminal with a link to documentation I'm delighted. And surprised.

Once upon a time, I worked at a financial startup (the company is irrelevant). I created a little harness around a static analysis tool. It would fail builds when a library had an outstanding vulnerability scored as HIGH or SEVERE with a patch available. The harness put a friendly error message around it. It ran roughly as follows:

> Hi! If you're reading this message, it's likely because this tool failed your build. To understand why and fix it, please click this link . Below is a table that lists the packages you need to update and the version you need to update them to.

The doc had at the very top in big flashing red text with siren anigifs a link to the portion that explained that they needed to update their libraries with very clear copy-paste-into-Dockerfile actionable guidance. The page also explained the broader context, such as the point of the tool and why we were doing this despite having a firewall and so on.

This is where you might be delighted and surprised.

What was perhaps less delightful and surprising were the consequences for me. About 4-6 times a week, I would then have a Slack conversation akin to this:

    Dev: Why did you break my build!?!

    Me: Can I see the error message?

    Dev: 

    Me: Thanks! Looking at the message, is there something unclear about the documentation? Does it not work?

    

    Dev: Nope! Docs are great!
At this point the conversation would end.

Re: Write better error messages

#86

Post by monknomo »

nerdponx wrote: post #38
jimmytidey wrote: post #26

Earlier quoted context omitted.

This is a context where people are used to seeing errors that they don't know what to do with. If a web app pops a well written error it is much more likely to be acted on than an unmotivated dev seeing a some (probably badly formatted) text. Every time I see an error in terminal with a link to documentation I'm delighted. And surprised.

So? That's no excuse for a developer to disregard the content of an error message in their own application.

And yet developers do disregard the content of error messages. Try to figure out why they disregard it. I doubt the answer is "because they're stupid". The answer probably also isn't "because they just aren't trying".

What could it be? Why do people read things and react in similar ways, even if they have different jobs? If only there was some field of study that could answer these mysteries.

Re: Write better error messages

#87

Post by marklubi »

nkrisc wrote: post #82
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 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.

Re: Write better error messages

#88

Post by coldacid »

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 help desk guys are on the other side of a cubicle wall from my workstation, and almost every call I overhear about someone getting errors just convinces me further and further that people don't only not pay attention to the error message, they don't pay attention to the people they're calling to help them get through the situation either.

Re: Write better error messages

#89

Post by prerok »

dementiapatent wrote: post #23
mariusmg wrote: post #17

Earlier quoted context omitted.

>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 ?

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 deliberate process to describe why we want to change it, what the impact is, etc. Tell me you want 100 new messages and you will be stuck in meetings for the next month.

In their case, though, it seems they at least have the support in management for it. I hope it turns out better for them than it did for me.

Re: Write better error messages

#90

Post by bombcar »

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.

Some of the errors that Gentoo portage can encounter do exactly this - and they do it with beautiful terminal colors that make it easy to figure out what you need to run, or where to go to figure out which of the three options you need.

The problem can come when there's a wall of "useless" logging/error messages, and the last one or near the last one is the actual important one to look at. You have to explicitly call it out on a clear screen and make it obvious - and even then, people won't always read it.

Post reply on HN