Error messages
- New
- Reference
- 5-min read
Error messages tell users something went wrong, why it happened, and what to do next. A well-written error message reduces uncertainty and turns a dead end into a recoverable step.
Choose the right component or pattern
There are multiple components designed for displaying errors, warnings, and user feedback. Before anything, check whether the error can be prevented or whether a different pattern fits. Not every problem needs an error message.
-
Prevent it first. Show a confirmation dialog before irreversible or risky actions, such as permanently deleting or overwriting. Label the button with the specific action ("Delete", not "Confirm") and keep "Cancel" available. See Modal for reusable text.
-
If there's nothing to show, use an EmptyState. This applies when nothing has been created yet, a search has no results, or an error prevented data from loading.
-
To communicate an entity's status rather than an error to act on, use a HealthIndicator. It shows the state at a glance without taking over the page, and it's best for an ongoing status that users can check at their own pace.
| Component or pattern | When to use |
|---|---|
| Forms and validation | For field errors:
|
| MessageContainer | For persistent, contextual messages scoped to the current page or section:
|
| Toast | For temporary, non-disruptive feedback:
|
Severity and placement
Match the component's disruptiveness, color, and icon to the error's severity:
| Error severity | How it appears | Icon and variant | Examples |
|---|---|---|---|
| Low | Inline or below an input — doesn't interrupt the user's flow |
|
|
| Medium | Page-level summary at the top of the view — interrupts until acknowledged |
|
|
| High | Blocking modal or full-page error — blocks entirely until resolved |
|
|
Never rely on color alone to signal severity. Always pair an icon with text so the meaning remains clear for users who can't distinguish colors. For both warning and critical states, use the base icon (WarningIcon or CriticalIcon) when something needs attention, and the failed variant (WarningFailedIcon or CriticalFailedIcon) when a process has failed.
Error messages should sit as close to the source of the problem as possible:
- Place field errors directly below its input and clear it when the value is valid.
| Do | Don't |
|---|---|
| Add an end time after the start time. | Invalid time range. |
- When applicable, show a summary that mirrors each field's exact wording so the summary and field errors read identically. Place it where the problem surfaces: near the submit button for form errors that appear on submission, or at the top of the view or its relevant section for issues not tied to a direct form, such as a missing configuration.
| Do | Don't |
|---|---|
To save your configuration:
| Validation failed:
|
Write effective error messages
Use the format that gives users just enough context to understand and resolve the problem. A field-level validation error may be a single line of text, while a system failure may need an icon, title, details, and an action. Whatever the shape, the same writing principles apply.
Use simple words
Explain what happened in plain language. Avoid jargon and internal Dynatrace terminology unless it's industry standard.
| Do | Don't |
|---|---|
| Your query reached the data scan limit. Narrow the time range or add filters. | Query exceeded max scan bytes threshold. |
Be specific
Use exact numbers, dates, and formats.
| Do | Don't |
|---|---|
| Passwords must be at least 16 characters. | Password is too short. |
Show a way forward
Lead with the most likely cause or simplest fix. If the problem might recur, add a fallback such as contacting support. When one action resolves it, offer that action directly. Label it with one or two imperative words instead of vague labels.
| Do | Don't |
|---|---|
| Retry | OK |
| Refresh | Done |
Skip obvious next steps
When space is limited, and the solution is self-explanatory, leaving it out can help the user by giving them fewer words to read. In the example, there's no need to tell the user to double-check their command. It's already self-explanatory and its location in the query will be highlighted.
| Do | Don't |
|---|---|
| There's no command 'testing'. | There's no command 'testing'. Please double-check your command and rerun your query. |
Avoid generic errors or raw codes
Unless no further context is available, don't fall back on "Something went wrong". Even then, pair it with plain-language context or next step rather than showing it alone. When surfacing server-side errors (400, 401, 403, 404, 500, etc.), follow the Error handling reference. Don't make a raw error code the entire message.
| Do | Don't |
|---|---|
| 404 The page you're looking for doesn't exist. | Error 404. Something went wrong. |
Don't assign blame
Lead with the value or action the user needs, not with what they did wrong.
| Do | Don't |
|---|---|
| Use a value between 1 and 100. | You entered an invalid value. |
Don't be overly apologetic
Apologies aren't necessary, unless we caused a big inconvenience. Stay calm and supportive. Avoid humor, idioms, or phrases that may not translate.
| Do | Don't |
|---|---|
| Couldn't save your changes. Try again later. | We're really sorry! An error occurred. |
Don't exaggerate or downplay
This might cause the user to panic or ignore an error that needs attention. Adjust the tone according to the error's severity. Skip filler words like "Oops!" or "Uh oh!".
| Do | Don't |
|---|---|
| Couldn't load data. Check your connection and try again. | Uh oh! Nothing here. |