How to create 404 page in astro

AstroHow-ToBeginner · 3 min read

How to Create a 404 Page in Astro: Simple Guide

In Astro, create a 404.astro file in your src/pages folder to define a custom 404 page. Astro automatically serves this page when a user visits a non-existent route.

📐

Syntax

To create a 404 page in Astro, add a file named 404.astro inside the src/pages directory. This file should export a component that renders the content shown when a page is not found.

Astro uses the file name 404.astro to detect the 404 error page automatically.

astro

---
// No frontmatter needed unless you want to add scripts or imports
---
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Page Not Found</title>
  </head>
  <body>
    <h1>404 - Page Not Found</h1>
    <p>Sorry, the page you are looking for does not exist.</p>
    <a href="/">Go back home</a>
  </body>
</html>

Output

A simple webpage with a heading '404 - Page Not Found', a message, and a link to the homepage.

💻

Example

This example shows a complete 404 page in Astro with basic styling and navigation back to the homepage.

astro

---
// src/pages/404.astro
---
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>404 Not Found</title>
    <style>
      body {
        font-family: Arial, sans-serif;
        text-align: center;
        padding: 4rem;
        background-color: #f9f9f9;
        color: #333;
      }
      a {
        color: #007acc;
        text-decoration: none;
        font-weight: bold;
      }
      a:hover {
        text-decoration: underline;
      }
    </style>
  </head>
  <body>
    <h1>404 - Page Not Found</h1>
    <p>Oops! We can't find the page you're looking for.</p>
    <a href="/">Return to Homepage</a>
  </body>
</html>

Output

A styled 404 page with a centered message and a clickable link to the homepage.

⚠️

Common Pitfalls

Not naming the file exactly 404.astro will prevent Astro from recognizing it as the 404 page.
Placing the 404 page outside src/pages means it won't be served automatically.
Forgetting to include a link back to the homepage can confuse users.
Not setting the lang attribute or meta tags can hurt accessibility and SEO.

astro

---
// Wrong: File named not404.astro
---
<html><body><h1>Wrong 404</h1></body></html>

---
// Right: File named 404.astro in src/pages
---
<html lang="en"><body><h1>Correct 404</h1></body></html>

📊

Quick Reference

File name: 404.astro
Location: src/pages/
Purpose: Displayed automatically for unknown routes
Accessibility: Use lang attribute and semantic HTML
Navigation: Provide a link back to home or main pages

✅

Key Takeaways

Create a file named 404.astro inside src/pages to define your 404 page.

Astro automatically serves this page for any unknown URL.

Include clear messaging and a link back to the homepage for better user experience.

Use semantic HTML and accessibility best practices in your 404 page.

Ensure the file is correctly named and placed to avoid it being ignored.