Customizing the 404 Error Page

Customizing the 404 Error Page

In the previous chapter, we set up the contact form with Formspree. Now we will customize the 404 error page — the page visitors see when they land on a URL that does not exist.

A well-designed 404 page does more than apologize. It guides lost visitors back to the content they were looking for, reducing bounce rates and keeping them on your site. Nuxas includes a clean, friendly 404 page out of the box, and this chapter shows you how to customize it.

What Is a 404 Error?

When a visitor requests a page that does not exist, the server responds with a status code called 404 Not Found. This tells the browser that the page could not be found. Nuxt automatically shows the 404 page whenever a visitor lands on a URL that does not match any route in your project.

Common reasons a visitor might land on a 404 page:

• They mistyped a URL.
• They clicked a broken link from another site.
• A page they bookmarked has been deleted or renamed.
• They manually changed the URL in the address bar.

A good 404 page acknowledges the error and offers clear next steps.

How to Edit the 404 Page

As with the previous chapters, the way you edit depends on your edition.

If You Purchased the Code + Decap CMS Edition

Open http://localhost:3000/admin. In the left sidebar, click 404 Page. You will see a form with every field in the 404 configuration.

Edit any value, then click Save in the top right corner. The change is written to content/404.md, and the Nuxt development server reloads the page automatically.

If You Purchased the Code Only Edition

Open content/404.md in VS Code. The file is small — just a few lines of frontmatter. Edit any value, then save with Ctrl + S.

Understanding the 404 Configuration

The 404 page configuration lives in content/404.md. It has five fields:

title: 404 — Route Not Found | NuxtSass Starter
description: The page or endpoint you requested does not exist on NuxtSass Starter. Return to the homepage, browse the Nuxt templates, or read the engineering blog.
badge: "404"
heading: Route Not Found in Nitro Dispatcher
intro: The page or endpoint you are looking for has been moved, renamed, or never committed to the router. Double-check the URL or return to our core directories below.
links:
  - label: Return to Homepage
    to: /
    variant: primary
  - label: Browse Templates
    to: /products
    variant: secondary
  - label: Read Our Blog
    to: /blog
    variant: ghost

Here is what each field does:

• title — the browser tab title and the SEO title. It appears in search engine results, though 404 pages are usually not indexed.
• description — the SEO description. Like the title, it is rarely shown, but it is good practice to fill it in.
• badge — the large number or short text at the top of the page. In the default config, it is "404". You can change it to something like "Oops" or "Lost?".
• heading — the main heading of the page, rendered as an <h1>. The default is "Route Not Found in Nitro Dispatcher". You can change it to something more friendly like "We Could Not Find That Page".
• intro — a paragraph below the heading, explaining what happened and what to do next.
• links — a list of buttons below the intro. Each button has a label, a to (the URL), and a variant.

Understanding the Link Variants

The links section supports three variants:

• primary — a filled button in the brand color. Use this for the most important action, usually "Return to Homepage".
• secondary — a glass button with a subtle border. Use this for secondary actions, like "Browse Templates".
• ghost — a text-only button. Use this for tertiary actions, like "Read Our Blog".

You can have as many links as you want. A common pattern is one primary link (homepage), one secondary link (products or services), and one ghost link (blog or contact).

An Example: A Friendlier 404 Page

Here is an example of a 404 configuration with a friendlier tone:

title: Page Not Found — My SaaS
description: The page you are looking for does not exist. Return to the homepage or browse our latest articles.
badge: "Oops"
heading: We Could Not Find That Page
intro: It looks like the page you are looking for has been moved, renamed, or never existed. Do not worry — here are some helpful links to get you back on track.
links:
  - label: Go to Homepage
    to: /
    variant: primary
  - label: Browse Products
    to: /products
    variant: secondary
  - label: Read Our Blog
    to: /blog
    variant: ghost
  - label: Contact Us
    to: /contact
    variant: ghost

This configuration has a warmer tone, four links instead of three, and a more descriptive intro. Feel free to adapt it to your brand voice.

Testing the 404 Page

To see the 404 page in action, open your browser and go to a URL that does not exist. For example:

http://localhost:3000/this-page-does-not-exist

You should see the 404 page with your customized content. If you see a generic error page instead, check that content/404.md is saved correctly and that the heading, intro, and links fields are valid YAML.

If you are editing through the CMS, remember to click Save after every change.

How Nuxt Handles the 404 Page

Nuxt has a special file called app/error.vue that handles all errors, including 404 errors. When a visitor lands on a nonexistent URL, Nuxt calls error.vue with a status code of 404. The component reads the 404 configuration from content/404.md and renders it.

If you want to customize the error page further — for example, to show a different message for 500 errors — you can edit app/error.vue. The file has logic to distinguish between 404 errors and other errors, and to show different content for each.

For most users, editing content/404.md is enough. The component handles the rest.

Common Mistakes

Mistake 1: Forgetting to quote the badge

The badge field is a string. If you set it to 404 without quotes, YAML will interpret it as a number. Nuxt expects a string, so the page may fail to render. Always quote the badge:

badge: "404"

Mistake 2: Missing a required field

Every field in content/404.md is required. If you delete a field, the page may fail to render. If you want to remove a field, check content.config.ts to see whether it is optional. The links array is required, but it can be empty if you do not want any buttons.

Mistake 3: Invalid link variant

The variant field must be one of primary, secondary, or ghost. If you use a different value, the button will render with default styling, which may look inconsistent.

What to Expect in the Next Chapter

In the next chapter, we will manage blog posts — creating, reading, updating, and deleting them. This is the largest chapter in the documentation, because blog posts have the most fields. We will cover the entire process from start to finish, with examples and screenshots-in-words.

If you purchased the Code + Decap CMS edition, you will learn how to manage blog posts through the CMS dashboard. If you purchased the Code Only edition, you will learn how to edit Markdown files directly.

See you in the next chapter.