Style storefront error pages (404 and 503)

When a visitor asks for a page that doesn’t exist, or the storefront hits an error, Fluid renders an error template from your theme. A theme has two error templates, and each one covers its own set of errors:

error_page/404/index.liquid renders for pages that can’t be found.
error_page/503/index.liquid renders when something goes wrong while Fluid builds a page.

Without them, visitors see a plain Fluid page instead of your storefront.

How Fluid picks an error template

Fluid looks up error templates by name in your active theme, or in the theme you’re previewing (see Preview your error pages):

The template type is error_page, and the template name is the status code, 404 or 503. A template with any other name never renders, including one named default.
The template must be the default for its name, and it must have a published version. Fluid renders the published version, not your latest saved draft.
The 404 and 503 templates are independent. Making one of them the default doesn’t change the other.

There’s one pair of error templates per theme. Theme region rules don’t apply to them, so you can’t assign a different error template to a country.

When each template shows

What happened	Template	Status code	Visitor’s URL
A path that matches no storefront route, such as `/home/spring-catalog/2024`	404	`404`	Unchanged
A page disabled for the visitor’s country by a theme region rule	404	`404`	Unchanged
A page set to its own direct path, opened through a rep’s link such as `/jane-doe/about-us`	404	`404`	Unchanged
A product, page, collection, category, post, media item, playlist, or enrollment pack that doesn’t exist or is no longer available, or a rep site for a username that doesn’t exist	404	`404`	Unchanged
An unexpected error while Fluid renders a page	503	`503`	Unchanged
A request that fails Fluid’s security checks, such as a form submitted with an expired session	503	`503`	Unchanged

A path with a single segment, such as /spring-sale, is read as a rep’s username. When no rep has that username, Fluid shows your home page rather than a 404. Fluid renders the 404 for a missing record in place, at the URL the visitor asked for, when the request accepts HTML. A request that doesn’t accept HTML, such as one that asks only for JSON, is redirected to /404 instead, and /404 answers JSON requests with a JSON error body rather than a page. A rep site link that names no rep, /my/home, redirects to your home page rather than showing a 404. A share link, /s/<token>, that is unknown or has nowhere to go redirects to /404 instead.

Pages your theme can’t style

Some responses never reach your theme:

Storefront paused for billing. If Fluid pauses your storefront over an unpaid balance, visitors see a fixed “temporarily unavailable” page with status 503. Search engines are told not to index it, and it isn’t cached. See the Status card on Billing.
Storefront unreachable. If Fluid can’t reach your storefront’s servers, visitors get a plain-text 502 response.
Rate limiting. A visitor who sends too many requests gets a 429 response with a JSON body.
Blocked addresses. A request from a blocked IP address gets a 403 response with a JSON body.
Unknown storefront. If Fluid can’t tell which company a domain belongs to, it shows its own static error page.

Fluid has no maintenance, password, or coming-soon mode for themes to style.

What happens without error templates

When the active theme has no published default template for a status code, Fluid shows its own static page instead. That page is dark, carries the Fluid WeCommerce branding, and has none of your navigation. An unexpected error that falls back to this page returns status 500 rather than 503. Whether your theme already has error templates depends on how you created it:

Theme source	Error templates
A copy of the Base theme	Included
A copy of the Vox or Fluid theme	Not included
`fluid theme init`	Not included
An imported theme	Only if the import includes them
A copy of another company theme	Whatever that theme has

Add both error_page/404/index.liquid and error_page/503/index.liquid to every theme you publish. Importing a theme that includes them makes each one the default and publishes it. Pushing them with fluid theme push publishes each one, and makes it the default for its status code when that code has no default yet. The 404 and 503 are handled separately, so pushing both makes both the default.

Until recently, a push made only the first error template the default, and themes pushed then weren’t corrected. If you pushed both error templates before that, open the Error Page folder in the Page Editor and use Make Default on any error template that doesn’t show the bookmark icon.

Layout and variables

An error template renders inside your theme layout, layouts/theme.liquid, so your navbar, footer, and storefront Global Embeds appear on it. Use the layout tag to change that:

{% layout 'checkout' %} renders the template inside layouts/checkout.liquid.
{% layout none %} renders the template without a layout. The template must then output the whole document.

What `content_for_header` adds on error pages

On other storefront pages, {{ content_for_header }} adds the page title, meta tags, Fluid’s scripts, and your theme’s stylesheets. On an error page, it outputs only the storefront Global Embeds placed in the head. So your error pages depend on your layout for these:

Stylesheets. Load your theme CSS from the layout with asset_url and stylesheet_tag, as the developer guide recommends. A theme that relies on Fluid to add its stylesheets renders error pages without them.
Title. Fluid doesn’t add a <title>. Give error pages one from the layout, as shown below.

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  {% if request.page_type == 'error_page' %}
    <title>{{ error.status_message }} | {{ company.name }}</title>
  {% endif %}
  {{ content_for_header }}
  {{ 'theme.css' | asset_url | stylesheet_tag }}
</head>

Variables

Error templates receive these values:

Variable	Description
`error.status_code`	`404` or `503`
`error.status_message`	`Page not found` or `Something went wrong`. Always English
`base_url`	Storefront base URL
`logo_url`	Company logo, or Fluid’s logo when the company has none
`shop_url`	Attributable shop URL

The global variables are available too, including company, localization, country, request, params, affiliate, routes, privacy_policy_path, terms_conditions_path, navbar, footer, sections, and the on-demand collections such as products and collections. A few of them read differently on an error page:

request.page_type is error_page.
request.path depends on why the page shows. When a missing record shows the 404, it’s the path the visitor asked for, such as /home/products/winter-blend. In the other cases, it’s the error route, such as /404 or /500, not the path the visitor asked for.

Localize the messages

Most error pages render in English, whatever language the visitor has selected, and the t filter reads your English locale file, locales/en.json, on them. A 404 for a missing enrollment pack, playlist, or rep site renders in the visitor’s language.

Put your error text in your locale files, and give every key an English value. Add default: straight after t to give each string your own fallback text. When no locale file defines the key, the fallback shows, and a blank check on the result is true. Without default:, a missing key renders as “Translation missing” text on the page. Keep other filters after default:: a filter between t and default: turns the missing-key text into ordinary text, and default: keeps it.

locales/en.json

{
  "error": {
    "page_not_found": "We can't find that page",
    "page_not_found_message": "The link may be out of date, or the page may have moved.",
    "service_unavailable": "Something went wrong on our end",
    "service_unavailable_message": "Please try again in a few minutes.",
    "continue_shopping": "Continue shopping",
    "go_home": "Back to the home page"
  }
}

Add the same keys to your other locale files, for the error pages that follow the visitor’s language. The Base theme’s error templates use t with default:, and its locale files define their error.* keys in all 19 of its languages. A theme copied from Base before those keys were added has the templates without the keys, so its error pages show the templates’ English fallback text.

Example template

This template works as both error templates. Save the same file as error_page/404/index.liquid and error_page/503/index.liquid, and it branches on error.status_code.

error_page/404/index.liquid

{% layout 'theme' %}
{{ 'template-error-page.css' | inline_asset_content }}

{% if error.status_code == 503 %}
  {% assign heading = 'error.service_unavailable' | t | default: "Something went wrong on our end" %}
  {% assign message = 'error.service_unavailable_message' | t | default: "Please try again in a few minutes." %}
{% else %}
  {% assign heading = 'error.page_not_found' | t | default: "We can't find that page" %}
  {% assign message = 'error.page_not_found_message' | t | default: "The link may be out of date, or the page may have moved." %}
{% endif %}

<section class="error-page">
  <a class="error-page__logo" href="{{ base_url }}">
    <img src="{{ logo_url }}" alt="{{ company.name | escape }}" width="160">
  </a>

  <p class="error-page__code">{{ error.status_code }}</p>
  <h1 class="error-page__title">{{ heading }}</h1>
  <p class="error-page__message">{{ message }}</p>

  <div class="error-page__actions">
    {% if error.status_code != 503 %}
      <a class="error-page__button" href="{{ shop_url }}">{{ 'error.continue_shopping' | t | default: "Continue shopping" }}</a>
    {% endif %}
    <a class="error-page__link" href="{{ base_url }}">{{ 'error.go_home' | t | default: "Back to the home page" }}</a>
  </div>
</section>

Keep the page’s CSS in assets/, the same as any other template’s CSS. The Base theme names these assets after the template, assets/template-error-page-404.css and assets/template-error-page-503.css, and loads each one with inline_asset_content from its template. A shared file such as assets/template-error-page.css works the same way.

Preview your error pages

You can preview an error template in two ways:

The Page Editor’s preview area renders the template you’re editing, from any theme, including saved changes you haven’t published. error.status_code and error.status_message are blank there, so the example above shows its 404 text for both templates.
Preview in the Page Editor opens the template on your storefront: /404 for a 404 template, and /errors/503 for a 503 template. The link names the template’s theme, so it works for a theme that isn’t active.

Error pages also follow a theme preview. While you preview another of your company’s themes on the storefront, or run fluid theme dev, the 404 and 503 pages come from that theme, including the 404 a missing record shows. If that theme has no published default template for the status code, you see Fluid’s static page, not your active theme’s template. That’s what visitors will see once you publish the theme.

Search engines and caching

Status codes. Error pages return a real error status. An unknown path or a missing record returns 404 at the URL the visitor asked for, and 503 tells search engines the problem is temporary, so they retry later.
Caching. Fluid’s CDN caches only successful HTML pages. Error responses are sent as private, no-store, so a visitor never sees a cached error page and a fixed page shows up straight away.
Indexing. Fluid doesn’t add a noindex tag to your error pages. The error status keeps them out of search results, so you don’t need one.

Start here

Building blocks

Storefront features

Advanced

Member storefront

Style storefront error pages (404 and 503)

How Fluid picks an error template

When each template shows

Pages your theme can’t style

What happens without error templates

Layout and variables

What `content_for_header` adds on error pages

Variables

Localize the messages

Example template

Preview your error pages

Search engines and caching

​How Fluid picks an error template

​When each template shows

​Pages your theme can’t style

​What happens without error templates

​Layout and variables

​What content_for_header adds on error pages

​Variables

​Localize the messages

​Example template

​Preview your error pages

​Search engines and caching

​Related pages

How Fluid picks an error template

When each template shows

Pages your theme can’t style

What happens without error templates

Layout and variables

What `content_for_header` adds on error pages

Variables

Localize the messages

Example template

Preview your error pages

Search engines and caching

Related pages