Skip to content
design
Foundations

Error messages

Something has gone wrong. Say what happened, why, what survived, and what to do next.

On this page
Waypoint not saved

The GPS lost its fix while saving. The waypoint is kept for this session. Try again when the fix is back.

Try againDismiss
VOICE“Couldn't save the waypoint because the GPS lost its fix. It's kept for this session; try again when the fix is back.”
An error in four parts: what happened, why, what survived, and what to do. The voice says the same in one sentence.

An error message reports a problem that has already happened. The person reading it is on a vessel at sea, often tired and often mid-task, and may be hearing it through a cockpit speaker. The message has one job: get them moving again without losing anything.

01Inform to build trustSay plainly what happened and why, when the cause is known. If it is not known, say that; never invent a cause.
02Show the way forwardTell the reader what survived and what to do next. A message that only reports a failure leaves them stuck.
03Own the problemSay “we” about what went wrong. Never blame the reader, and never blame a third party by name.

Anatomy

01What happenedCouldn’t save your waypoint.
02Why, when knownThe GPS lost its fix.
03What survivedIt’s kept for this session.
04What to doTry again when the fix is back.
  • Title (optional): three or four words that say what happened. Sentence case, no exclamation mark.
  • Body: one or two sentences covering the other parts. No error codes, stack traces or protocol names.
  • Actions (a toast): a verb that does the fix (Try again, Reconnect); an error toast stays until the crew dismiss it. A banner or a section message has no actions: it stays while the condition lasts, and its second line says what to do. Never OK.

A shipped example

The notice the instrument pages show when the NMEA network goes quiet is the four parts as the kit writes them: what stopped and for how long, what the page still shows, and what to check.

No instrument data

Nothing has arrived from the NMEA network for 2 min. The readings below are the last ones received, each marked with its age. Don't navigate by them until data returns.

Check that the instruments are switched on, then the NMEA gateway's power and cabling.

Voice and tone

Do
We're having trouble reaching the chart server. Charts on board still work; new tiles will load when the connection is back.
Own the problem and point at the fix.
Don't
You entered an invalid route. Garmin's API is down.
Don't blame the reader or a supplier, and don't stop at the failure.
Do
PIN too weakEvery digit is 0. Pick a PIN that mixes different digits.
Name the exact problem and the exact fix.
Don't
Oops!Something went wrong. Please try again later.
Don't write a catch-all. It tells the crew nothing and hides which case went wrong.

Patterns

Error or attention. An error says something has gone wrong. An attention message says something might, and comes before the action that would cause it.

A fallback is a missing classification. A generic "Something went wrong" means the code did not tell the errors apart. Each case the code can produce gets its own message. A last-resort message comes only after that, and still says what survived and what to do: "Nothing was changed. Try again; if it repeats, contact support."

Errors are not alarms. An error message reports a failed action. An alarm reports a hazard to the vessel or crew. An error message wears its mark in the neutral notification color, never an alert color. A notice that the data has stopped, such as the one above, takes the data integrity red, as an invalid reading does; a failed action takes no red.

Spoken errors

The voice gives the same four parts compressed into one sentence, most important fact first: "Couldn't save the waypoint — it's kept for this session; try again."

When the outcome is uncertain

Say “Nothing was changed” only when the application can establish that the action did not take effect. A lost connection after submission may leave the outcome unknown. Explain that uncertainty, retain the user's input, and offer a way to refresh the authoritative state before repeating an action that could have side effects.

Keep a field error beside its field and a submission failure beside the relevant form action. Include enough context to distinguish a rejected value, a permission failure and an unavailable service. Reports should record what was observed and what could not be verified, rather than converting a failed check into a successful result.