This tutorial explains how to create and configure a custom 404 error page for your Netlify-hosted applications, ensuring it replaces Netlify’s default 404 page.

Step 1: Create a Custom 404 Page

1. Design Your 404 Page

   Create a file named 404.html in the root of your project’s publish directory (often public, build, or dist, depending on your framework).

   This file will serve as your custom 404 page and will be automatically picked up by Netlify for any unresolved paths.

   Example content for 404.html:

   404 - Page Not Found

   Sorry, the page you're looking for doesn't exist.

   Return to Home

2. Customize as Needed

   Add your branding, styles, or links to match your site’s design.

   For SPAs (e.g., React, Vue, Next.js), you can use a framework-specific component (e.g., 404.js for Next.js) or generate a static 404.html during the build process.

Step 2: Place the 404 Page in the Correct Directory

• Static Sites

  Ensure 404.html is in the root of your publish directory (e.g., public/ for a vanilla HTML site or build/ for a React/Vue app).

• Framework-Specific Sites

  Next.js: Create a 404.js or 404.tsx file in the pages/ directory. Next.js automatically generates a 404.html during the build process.

  import Link from ‘next/link’;

  export default function FourOhFour() { return ( <>

  404 - Page Not Found

  Sorry, the page you’re looking for doesn’t exist.

  Return to Home </> ); }

  Vue/Nuxt: Create a 404.vue file in the pages/ directory (Nuxt) or handle routing in your Vue app to render a custom 404 component.

  React with React Router: Ensure your build process outputs a 404.html file, or configure redirects (see Step 3).

Step 3: Configure Redirects for SPAs (Optional)

For SPAs, client-side routing can cause 404 errors when users refresh or directly access routes (e.g., yoursite.com/about). To handle this, configure Netlify to redirect all unmatched routes to your index.html while ensuring the custom 404 page is served for truly invalid routes.

• Option 1: Use _redirects File

  Create a _redirects file in your publish directory (e.g., public/_redirects or build/_redirects).

  Add the following rule:

  /* /index.html 200 /* /404.html 404

  The first rule ensures client-side routes are handled by index.html, and the second ensures invalid routes fall back to 404.html.

• Option 2: Use netlify.toml File

  Create or edit a netlify.toml file in your project’s root directory.

  Add the following configuration:

  [[redirects]] from = ”/*” to = “/index.html” status = 200

  [[redirects]] from = ”/*” to = “/404.html” status = 404

  The netlify.toml file provides more flexibility and is recommended for complex setups.

Step 4: Deploy to Netlify

1. Push Changes to Your Repository

   Commit your 404.html (or framework-specific 404 file) and _redirects or netlify.toml file to your Git repository.

   Ensure your build command (e.g., npm run build) generates the necessary files in the publish directory.

2. Configure Netlify Build Settings

   In the Netlify dashboard, go to your site’s “Deploys” settings.

   Verify the build command (e.g., npm run build) and publish directory (e.g., build/ or public/).

   Deploy your site by pushing changes to your connected Git repository or manually uploading the publish directory.

3. Test the Deployment

   Navigate to a non-existent route (e.g., yoursite.netlify.app/does-not-exist).

   Confirm that your custom 404 page is displayed instead of Netlify’s default 404 page.

Step 5: Test and Troubleshoot

• Verify Locally

  For static sites, open 404.html in a browser to ensure it renders correctly.

  For SPAs, test locally (e.g., npm run dev) to confirm the 404 page works as expected (e.g., localhost:3000/does-not-exist).

• Check Netlify Deployment

  If the default Netlify 404 page appears, ensure 404.html is in the root of your publish directory and that the file is included in the deployment.

  For SPAs, confirm the /* /index.html 200 rule is present and takes precedence in your _redirects or netlify.toml file.

• Common Issues

  • Custom 404 Not Showing: Ensure the 404.html file is in the root of your publish directory and not nested in a subdirectory (e.g., /404/404.html won’t work unless explicitly configured).
  • SPA Routing Issues: If refreshing routes causes a 404, verify the /* /index.html 200 rule is present and takes precedence in your _redirects or netlify.toml file.
  • Framework-Specific Issues: For Next.js or Nuxt, ensure the custom 404 page is correctly named (404.js or 404.vue) and that the build process outputs it to the publish directory.

Step 6: Optional Enhancements

• Multi-Language Support

  For sites with multiple languages (e.g., /en/ and /es/), create language-specific 404 pages (e.g., /en/404.html, /es/404.html) and configure redirects in netlify.toml:

  [[redirects]] from = “/en/*” to = “/en/404.html” status = 404 conditions = { Language = [“en”] }

  [[redirects]] from = “/es/*” to = “/es/404.html” status = 404 conditions = { Language = [“es”] }

  Ensure the 404 pages are placed in the correct language-specific directories in the publish directory.

• Dynamic 404 Pages

  For frameworks like Next.js, use dynamic data in your 404 page (e.g., fetching suggested links via an API).

  Ensure the page is pre-rendered or statically generated during the build process to avoid runtime errors.

• Styling and Branding

  Match the 404 page’s design to your site’s theme using CSS, images, or framework-specific styling (e.g., Tailwind CSS for React apps).

Notes

• Netlify automatically serves 404.html from the root of the publish directory for any unresolved paths, so no redirect rules are required for basic static sites.
• For SPAs, the /* /index.html 200 rule is critical to handle client-side routing, but ensure it doesn’t override the 404 rule.
• If using a framework, always test the 404 page locally before deploying to ensure compatibility with Netlify’s static hosting environment.
• For complex setups (e.g., role-based or geo-based redirects), consult Netlify’s redirect documentation for advanced configurations.

By following these steps, you’ll have a custom 404 page that aligns with your brand and provides a better user experience than Netlify’s default 404 page.