Skip to contentShopify logoPolaris

Error messages

Make it clear what went wrong and how to fix it

Error messages should:

  • Explain what’s wrong and what the merchant needs to do
  • Be specific (exact numbers and dates, or even the merchant’s own data)
  • Don’t overapologize or bring “us”/”we” into the conversation unless Shopify caused the problem
  • Avoid error jargon like “invalid”
  • Use detailed instructions for the next step
  • Help merchants avoid mistakes in the first place, using clear content to manage expectations and highlight potential risks
  • Only explain what happened behind the scenes when it’s helpful to merchants or you can’t offer a solution

As always, follow all our content principles of keeping it short, using plain language, and getting rid of repetition. Also, good design can reduce the need for error messages by preventing them.

Design for clarity

  • Use iconography and color to communicate the severity of the problem and draw the merchant’s attention to what’s wrong
  • Place the error close to what needs fixed
  • Use red for critical messages that merchants need to deal with immediately to avoid harm to their business form validation errors
  • Use yellow for errors that are part of a daily workflow or warnings that could lead to critical errors if not addressed

Anatomy of an error message

Heading (optional)

  • Clearly state the effect of the error on the merchant
  • Command immediate attention

Body

  • If you don’t have a header, clearly state the effect of the error on the merchant
  • Explain how to fix it
  • Link to help documentation

CTA (optional)

  • Provide a one-step solution
  • Take merchants to another location expressly for fixing the issue

Examples

Multiple errors

Do

To save this product, make 2 changes:

  • Enter title
  • Add weight
Don't

There are 2 errors on this page.

  • Invalid title
  • Weight must be a number value greater than 0.1 lb

Settings warning

Do

Changing store currency will affect reporting, pricing, and more

Don't

Are you sure you want to change your currency?
Your new currency isn’t supported by PayPal Express.

Admin unavailable

Do

Heading: The page you’re looking for isn’t available
Body: Check the web address or try again later
Button: Retry

Don't

Heading: That page doesn’t exist
Body: You must have the wrong address
Button: Shopify Home

Do

Heading: Couldn’t deposit payout
Body: The bank account we have on file was closed. Update your details, and we’ll retry automatically. Button: Update bank account

Don't

Heading: Invalid bank account Body: Your payout was not deposited because your bank account was closed. Go to your bank account details and update them to match a valid checking account. Then save so that we can retry. Button: Next

Toast

Do

Connection timed out

Don't

Sorry, the connection time out. Try again later.

Errors without solutions

Do

Something went wrong. Refresh your browser to try again.

Don't

Sorry, something went wrong. Learn more.

    On this page