Error messages

    Error messages can be scary. Make errors visible to merchants, easy to understand, and helpful.

    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

    Text field validation

    Settings warning

    Use when:

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

    Settings warning error

    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

    Yellow page level banner

    Red page level banner

    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

    Yellow section level banner Yellow field level banner

    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

    Warning exception list error

    Critical exception list error

    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

    Yellow home notification

    Red home notification

    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

    Admin page not found error

    Admin page load error


    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

    Red banner with high fraud risk message

    Don’t

    Yellow banner with high fraud risk message

    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

    Form validation with red banner

    Don’t

    Form validation with yellow banner

    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

    Yellow banner with warning message

    Don’t

    Red banner with warning message


    Anti-patterns

    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

    Toast error message

    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

    Modal error message

    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.

    Don’t

    Home notification error message


    Form validation

    Text field validation

    Use when:

    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:

    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.

    Text field validation error

    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.

    Initial validation check with purple border

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

    Text field turns red

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

    Text field validation with cursor by incorrect semi colon

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

    Text field validation with purple border

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

    Text field validation in loading state with spinner


    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:

    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:

    Red form validation banner

    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

    Instructional validation banner

    Don’t

    Validation banner that only points out that there is an error

    Usage

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

    Spinner displaying on save

    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

    Validation error for a price entry 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

    Red form validation banner


    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:

    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

    In line warning banner below a drop down


    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

    Error message with arrows pointing at different parts of the message

    Don’t

    • Unable to process payment for checkout with negative taxes.

    Component:

    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.

    Page level warning banner

    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:

    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

    Warning banner at the top of a card below the card title Small warning banner in a section within a card


    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:

    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

    Exception list warning

    Exception list error


    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

    Structure of home notification with a header, body content, and button

    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

    Warning home notification with credit card expiry message

    Don’t

    Warning home notification with chargeback message

    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

    Critical home notification with account on hold message

    Don’t

    Critical home notification with out of stock message


    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

    Page not found error with internet connection message

    Don’t

    Page not found error with oops, something went wrong message

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

    Do

    Problem loading page error with troubleshooting tips

    Don’t

    Problem loading page error with content that talks about operational engineers

    Component:

    Note: Use of the empty state component is temporary for admin unavailable errors. This is an opportunity for someone at Shopify to explore a new design and help with creating UX guidelines. If you have ideas, create an issue (private).

    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

    Page not found error


    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

    Carrier may not be able to pick up package error message Carrier may not be able to pick up package error message

    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.

    Do

    • This error message is a last resort: "Something went wrong. Please try again in a few minutes."

    Don’t

    • An error occurred
    • 1 error
    • Invalid

    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.

    Do

    • Some of today’s sales data isn’t updated yet. This will be fixed soon. Your data is safe, and your actual sales are not affected.

    Don’t

    • Today’s sales data might not be accurate, but please don’t worry—it’s just temporary.

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

    Do

    • Product weight can’t be negative. Change the product weight to be 0 or higher and try again.

    Don’t

    • Error Line items grams must be greater than or equal to 0.

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

    Do

    • High risk of fraud detected

    Before fulfilling this order or capturing payment, review the Risk Analysis and determine if this order is fraudulent.

    Don’t

    • Uh oh! High risk of fraud detected

    Looks like there’s a high fraud risk with this order. Better review the Risk Analysis to make sure the order is safe!

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

    Do

    • There’s a problem loading this page

    There’s a technical problem with Shopify that has prevented this page from loading. Try reloading this page or going to another page in Shopify. If that doesn’t work, visit our status page for updates and try again later.

    Don’t

    • There’s a technical problem with Shopify that has prevented this page from loading. Our operation engineers are aware of this problem and are working hard to get it solved.

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

    Do

    • Before you can view earnings from your store, you need to complete your account setup. [Complete account setup]

    Don’t

    • Before we can provide you with earnings from your store, we need some additional information. [Complete account setup]