Custom 404 Page
When a user accesses a path that does not exist in an EdgeOne Pages project, the platform will provide a standard 404 error page. To ensure user experience consistency, the platform recommends creating a custom 404 webpage.
Static Site Generator (SSG)
For applications built with static site generators such as Gatsby or Hugo, or those generating multiple HTML files during build, ensure the build output directory contains a
404.html file. Pages will automatically identify this file during deployment and return it as the 404 page when no matching path is found for the request.
Hugo: Create 404.html in
./layouts/ or the theme directory ./themes/your-theme/layouts/.Gatsby: Create 404.js or 404.tsx in
./src/pages/.
Single-Page Application (SPA)
For SPAs built with modern frontend frameworks like React and Vue, error handling for 404 is normally handled by client-side routing. Set a "catch-all" or wildcard route in the routing configuration to handle all unmatched paths.
Note:
Note: Do not place 404.html in the root path of the output directory for SPAs, as it may impact client-side routing configuration.
React: Add a
path="*" Route at the end of the routing configuration using the react-router-dom, the most commonly used routing library in React, and bind it to your element pointing to a custom 404 component.Vue: Add a
path: '/:pathMatch(.*)*' routing rule in the Vue Router routing configuration array, and bind it to your component pointing to a custom 404 component.
Server-Side Rendering (SSR)
Pages now support server-side rendering (SSR) mode for the following full-stack frameworks. Since each framework handles 404 pages differently, the following lists the configuration method for each framework to ensure your application can display a custom 404 page correctly.
Next.js
Next.js provides a flexible method to handle 404 pages, but due to the existence of Pages Router and App Router, their 404 page configuration modes vary slightly.
Pages Router: Create a
404.js or 404.tsx file under the pages directory. Next.js will compile it into a static HTML file during build and return this page for any unmatched route request.App Router: Create a
not-found.js or not-found.tsx file under the app directory (or any routing segment). When a user accesses a path with no page.js file, Next.js will automatically render the nearest not-found.js file.
Nuxt.js
Create an
error.vue file inside the app/ directory under your project. Nuxt.js will automatically render this page when it fails to match any route on the server or client, or raises an error during the rendering process.
Astro
Create a
404.astro file under your src/pages/ directory. Astro will automatically identify and use it during build. When the server receives a request that cannot match any page, it will render and return the contents of the 404.astro page with a 404 status code.
React Router (v7+)
Export a component named ErrorBoundary in the root route file (app/root.tsx). The framework leverages React Router's built-in error boundary mechanism to automatically capture all unmatched routes, throw a 404 response, and use your provided ErrorBoundary to render the error interface.
SvelteKit
Create a
+error.svelte file under your route root directory src/routes/ to create a global 404 page that captures all unmatched routes. You can also place +error.svelte files in any route subdirectory to create local error pages for specific route groups. For example, src/routes/dashboard/+error.svelte will handle all errors under the /dashboard/* path that haven't been captured by deeper levels.