Error messages

Error messages should:

• Tell merchants what happened. If there’s a solution, explain it. If possible, offer a one-click fix with a button. If there’s no solution, give troubleshooting instructions.
• Be placed close to the source of the problem.
• Communicate severity using the appropriate color and tone of voice.
• Use plain language.
• Be specific. For example, use precise numbers and dates.
• Be brief.

Good design can reduce the need for error messages by preventing them in the first place.

Error message types

Think about the scope of the error when selecting a message type. Is something wrong with the entire application, with the entire current screen, or with a specific element on the screen?

If the cause of the error is visible and the error just happened, show the error message immediately and as close to the source of the problem as possible.

Text field validation error

Use when:

• An error applies to a text field and feedback can be provided while merchants are typing

Settings warning

Use when:

• The form input is valid, but you want to warn merchants of a consequence they might not expect

Page-level banner: critical or warning

Use when:

• An error applies to the entire page
• The error is far down the page and it’s critical merchants see the message
• Multiple validation errors on the page need to be summarized
• The error was delayed and it’s okay to inform merchants of the problem when they return to the page

Banner in a card or modal: critical or warning

Use when:

• An error applies to a single card within the page, a single section within a card, or a modal
• You need to direct merchants to a page with multiple sections and you want to visually call out the section with the error

Exception list: critical or warning

Use when:

• A message placed within or next to a component can help merchants make better decisions about routine tasks

Home notification: critical or warning

Note: Home notifications should rarely be used for errors. Always attempt to display an error close to the source of the problem.

Use when:

• A high-priority task must be completed immediately to continue using Shopify or avoid losing money
• A feature doesn’t have a dedicated details page

Admin unavailable

Use when:

• A server error is preventing an entire page from being displayed, like with 400 or 500-series server errors
• Account permissions are preventing someone from accessing Shopify

Error colors

Red is the scariest error color. Only use red for critical messages that merchants need to deal with immediately to avoid harm to their business. For example, if merchants don’t act on the message right away, they might lose money or their store might be suspended.

Yellow error messages still demand attention, but are more appropriate for messages that are part of a daily workflow.

Red (critical)

Use critical messages to:

• Bring attention to urgent tasks. If not dealt with immediately, merchants' businesses will be noticeably impacted, like an account being suspended or money being lost.

Examples of critical message types:

• Update a payment method expiry date
• Unsuspend an account
• Review an order for fraud
• Fix a problem that’s preventing payment from being processed

Do

Don't

The one exception to using red is in form validation errors because this is a standard convention merchants are used to seeing outside of Shopify.

Do

Don't

Yellow (warning)

Use warning messages to:

• Help merchants fix issues so they can complete a common workflow or continue to the next step
• Notify merchants about upcoming expirations or pending requests that, if not dealt with soon, could lead to problems in the future

Examples of warning message types:

• Fix a problem before proceeding to the next step.
• Fix a problem at some point in a common workflow.
• There’s a pending request.
• There’s an upcoming expiration.
• Changing a setting might have unintended consequences. See settings warning.

Do

Don't

Anti-patterns

Don't

Avoid using toast for error messages

Although error toast is still available, we discourage its use. Toast messages are too short to adequately explain what went wrong and how to fix the problem. Because the toast component appears at the bottom of the screen and disappears after 3 seconds, it can easily be missed. Reserve toast for errors not caused by merchants, like a connection issue. Always try to use a banner to inform merchants about persistent errors.

Don't

Don’t use modals for errors

Modal dialogs are a good way to ask merchants to confirm a destructive action, but not to tell them an error has occurred. Modals block merchants until a decision is made, which is likely to make merchants feel pressured. Most errors don’t need to block access to the rest of the feature.

Don't

Avoid using home notifications for errors

Home notification errors are for high-priority tasks that merchants must complete immediately to continue using Shopify or prevent a negative impact to their business, like losing money. One exception is errors for features that don‘t have a dedicated details page.

Form validation

Text field validation

Use when:

• A text field has formatting requirements. Use this pattern to enhance validation on form submission.

Don’t use when:

• It takes more than a full second to validate input and display a message. If there’s a lag before a validation message appears, merchants might shift their attention and miss the error. Either find a way to improve the validation speed, or rely on the validation after form submission.
• The field is empty. Merchants might tab through a form before filling it out, and errors on empty fields can cause confusion and frustration.

Component

• Text field

Content

• Use two or three words to explain what’s wrong or what’s needed to fix the problem.
• Avoid using the word "invalid" to define an error. When appropriate, use "not valid" instead.
• Since the message is directly below the text field, the copy only needs to explain why the error happened. Optionally, the message can clarify what to do next or offer a one-click fix.

Usage

Do an initial validation check as soon as merchants finish typing in the field.

Merchants can be considered to be finished typing only when keyboard focus moves away from the field and there is at least one character in the field. This helps avoid marking the field as not valid before merchants are really done typing.

If the validation check fails, show an error message below the field.

Once a field has an error, complete validation checks after each keystroke.

Remove the error message as soon as the input becomes valid so merchants can immediately tell they fixed the issue.

If the validation process is less than a second but not instant, show a spinner on the field to indicate validation progress.

Validate on submit

Validate on submit is triggered when merchants press the form’s submit button. The submit button is often [Save], but can be another call to action.

Use when:

• Not all fields can be validated while merchants are typing. When a form is used for saving data, always validate on submit and validate text fields while typing. For example, if merchants never interact with a required text field, there’s no change to mark it as not valid until they press the submit button. The same applies to form controls other than text fields, such as radio buttons, and selects.

Don’t use when:

• A form doesn’t have specific validation requirements, or the form doesn’t save data. For example, a search form that returns no results should display an empty state, rather than a validation error.

Component

• Banner

And one or more of the following:

• [Text field]
• [Select]
• [Choice list]
• [Checkbox]
• [Radio button]

Content

Banner heading

• Use a colon to introduce the list.
• Make the heading instructional. Don’t just call out that there are {x} number of errors.

Banner body text

• Use the list component to itemize the errors
• Start each list item with the label of the field that isn't valid, and describe the action needed to fix it

Individual field error messages:

• See content guidelines for validation while typing

Rather than pointing out that there are {x} number of errors, be more descriptive. Explain that in order to save or continue, {x} number of fields need to be changed. For the bullet point instructions, see if you can word them to be more actionable, for example, “Add a discount code,“ instead of “Discount can’t be blank.“

Do

Don't

Usage

Always indicate submission progress. If the fields aren't valid, don’t clear or alter them on behalf of merchants during validation.

If the form submission has a single error:

• Move scroll position to the field that is not valid
• Focus the field
• Show an error message below the field

If the form submission has multiple errors:

• Move scroll position to the top of the screen
• Use a banner to display a summary of all the errors
• Show an error message below each field that is not valid so merchants can scroll through and make corrections

Settings warning

Use:

• To help merchants prevent potential mistakes
• When form input is valid, but you want to warn merchants of a consequence they might not be expecting

Don’t use:

• For actual error states

Tip: Explore ways to prevent the warning message from showing at all. Look for opportunities to add help text or other contextual information to surface or highlight potential risks or consequences of taking, or not taking, the action.

Component

• Banner without title

Content

• Since the warning message is in close context to the action that triggered the warning, it should be short
• Explain the risks or consequences of an action that’s just been taken
• These messages don’t have to start with actionable language, like, “Change currency.” Here are some options
  • Start with the word “This” and explain the consequence, for example, “This will affect inventory prices”
  • Start by noting the action, then explain the consequence, “Changing {x} will affect {y}”
• If available, link to a resource where merchants can learn more

Banners

Page-level banners

Use when:

• An error applies to the entire screen
• The error is far down the page and it’s critical that they see the message
• A form was submitted with fields that are not valid
• If the error was delayed, for example, an action was taken and the error doesn’t immediately appear in context

Don’t use when:

• It’s possible to place the banner [in context] because the source of the error is in view and the event that triggered the action just happened

For multiple error guidelines, see validate on submit

Page-level banner errors should explain:

• Where the error happened
• What happened
• Why it happened
• What to do next

Do

Don't

• Unable to process payment for checkout with negative taxes.

Component

• Banner

Content

Headings should:

• Clearly state the problem
• Not use punctuation

Body content should:

• Explain how to solve the problem.
• Use actionable language like “do x.” Don‘t use permissive language, like “you can x.” Be concise: no longer than 2 sentences.
• Use periods.

Calls to action should:

• Be action-led (verb+noun format)
• Aim for a one-click fix. If the error can be fixed via a single button or menu, offer that action directly in the error message.
• Open a dedicated error-correction view for more complex problems such as reviewing a risky order or editing an unverified customer address.
• Provide a link to documentation for information that may be valuable but can’t fit in a brief error message.

Banners in cards and modals

Use when:

• Merchants are engaged in a task flow and you want to warn them about potential issues with the task at hand, or inform them something has gone wrong
• Directing merchants to a page with multiple sections and you want to visibly call out the section with the error

Don’t use when:

• An error applies to the entire screen.
• The error is far down the page and it’s critical that merchants see the message.
• If the error was delayed. For example, an action was taken and the error doesn’t immediately appear in context. In these cases, use the page-level banner

Component

• Banner

Variant

• Without title

Content

• The more contextual the message, the less you need to say, so go straight to explaining what happened and how to fix
• Keep to one sentence
• Contextual banners don’t have titles
• Try to add a next step, whether in a button or link
• Use when there is more than one call to action

Exception lists

Use when:

• Items in a list are in a noteworthy state that you want to make merchants aware of, like a status, or piece of information (like a high risk order) that’s directly relevant to the information it’s connected to

Example:

• High risk order

Don’t use when:

• The source of the problem is an entire card or page

Component

• Exception list

Variant

• Status: critical or warning

Content

Content should:

• Highlight an exceptional state that encourages clicking on the list item
• Pair content with a warning or error icon
• Always lead with what went wrong
• A description is required
• A title is optional
• Links are optional but not common because the list item is actionable
• Be concise

Home notifications

Home notifications are primarily used to prevent merchants from losing money or help them continue using Shopify if they don’t act on the error message instructions immediately.

Use for:

• High-priority tasks that must be completed immediately to continue using Shopify or avoid losing money.
• Important enough tasks that we wouldn’t want merchants to navigate to another place in Shopify to find it, or stumble upon while completing another task.
• Errors for features that don’t have a dedicated details page. For example, before Shopify Capital had a details page, related status messages were temporarily surfaced in Home.

Don’t use for:

• Tips or advice
• Positive feedback
• Confirmation messages
• New feature announcements
• Status messages, other than those for Shopify Capital
• Messages that can be displayed in context
• Error messages that should be displayed in context
• Task-related errors like a problem with saving a page

Warning home notifications

Warning home notifications are pre-emptive. They let merchants know that their finances will be impacted if action isn’t taken in a couple days or more, or that an action can be taken to make money sooner.

• Financing request is pending
• Warn about upcoming expiration
• Pending status, like with Shopify Capital application status

Do

Don't

Critical home notifications

Critical home notifications inform merchants of issues that:

• Currently impact their finances
• Will have an impact on their finances if action isn’t taken immediately
• Prevent the normal operation of their business or account

Critical home notifications can be used for these message types:

• Trial expired
• Domain expired
• Credit card expired
• Account is suspended
• Shopify Payment payouts on hold
• Payment processing issues
• Payment authorizations expiring that day

Do

Don't

Admin unavailable errors

Sometimes the admin can’t be displayed due to a network issue, browser limitation, connection problem, or server issue. 400 and 500 series errors fall in this category. In these cases, always explain what went wrong and provide merchants with a troubleshooting step, like refreshing the page.

Use when:

• A page or the entire admin can’t be displayed

Don’t use when:

• The error can be placed in context, close to the source of the problem

Do

Don't

Don’t use internal language in error messages and avoid using question formats.

Do

Don't

Component:

• Empty state

Content

Headings should:

• Heading should explain what went wrong
• Body should help merchants troubleshoot the problem
• Call to action should provide the most probable fix, like reloading the page, or going to the previous page or Shopify Home

Errors without solutions

When a service issue occurs in Shopify or is caused by a third party, we don’t always have a solution to offer to merchants. In these cases, always explain what went wrong so they can attempt to troubleshoot. If available, provide them with a troubleshooting step, like refreshing the page or returning at a later time.

Use when:

• Merchants are being denied access to a page or the entire admin See admin unavailable errors
• A third party issue is causing a disruption to merchants’ workflows

Don’t use when:

• There’s literally any solution we can offer to merchants

Do

Don't

• Don’t use the “Something went wrong. Please try again in a few minutes.” message when there’s any option to offer more context.

Voice and tone

These content guidelines are based on common copy mistakes. Avoid sounding overly apologetic, too technical, or hyperbolic. Keep Shopify out of the conversation unless Shopify was the cause of the error. Don’t downplay the error by telling merchants not to worry or by adding humor to a negative situation.

Avoid the word “please” so it’s not overused throughout the admin. Don’t downplay serious problems.

Don’t use scary, technical words in error messages.

Error messages are not the place for hyperbole or injecting personality.

Don’t use internal Shopify terms. Only include the information merchants need.

Keep Shopify out of the conversation. Focus on the information merchants need to complete their task efficiently.