How to Create a Custom 404 Page in Astro

Replace the plain 'not found' error with a helpful page of your own. It takes one file.

By the Astro Nursery team. Review lead: Blaise Kavai, VP of ProductPublished November 6, 20263 minute readComplete beginner

When someone follows a broken link, they land on an error page. Astro lets you replace the plain one with a page of your own, and it only takes one file.

Step 1: Create the page

Create src/pages/404.astro. The name matters, so copy it exactly:

---
import Layout from '../layouts/Layout.astro';
---
<Layout title="Page not found">
  <h1>Page not found</h1>
  <p>That page doesn't exist. <a href="/">Go back to the home page</a>.</p>
</Layout>

Step 2: Check it

With the dev server running, visit an address that doesn’t exist, such as http://localhost:4321/nothing-here. Your new page appears.

When you run npm run build, Astro writes it to dist/404.html. That file name is what hosts look for.

Step 3: Make sure your host uses it

Most static hosts serve 404.html without any setup. On Cloudflare Workers, you need one line in wrangler.jsonc:

"assets": {
  "directory": "./dist",
  "not_found_handling": "404-page"
}

See how to deploy to Cloudflare Workers for the full file.

What makes a good 404 page

Say plainly that the page doesn’t exist. Don’t blame the visitor.
Offer a way forward: a search box, your most popular pages, or a link home.
Keep your normal header and footer, so the site still feels familiar.

Our own 404 page has a search button and the six topics people ask about most. Visit any made-up address on this site to see it.

Frequently asked questions

Why doesn't my 404 page show on my live site?

Your host has to know to use it. Most static hosts, including Netlify and GitHub Pages, serve 404.html automatically. On Cloudflare Workers, add not_found_handling set to 404-page in wrangler.jsonc.

Keep reading