---
title: Custom 404 Page
description: Create a custom 404 page and deploy with Vercel.
url: /kb/guide/custom-404-page
canonical_url: "https://vercel.com/kb/guide/custom-404-page"
published: 2025-11-03
last_updated: 2026-07-16
authors: Steven Salat
related:
  - /docs/concepts/deployments/build-step
  - /docs/concepts/deployments/configure-a-build
  - /docs/concepts/functions
  - /docs/concepts/projects/project-configuration
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---
<!-- docsgraph:related -->
## Related pages

> **For AI agents:** Follow these links to understand how this page connects to the rest of the Vercel ecosystem. For the full cross-link map (inbound, outbound, prerequisites, and semantic neighbors), see the .graph.md link below.

- [Custom Error Pages](https://vercel.com/docs/custom-error-pages?from=related) — Learn how to configure custom error pages for 5xx server errors on Vercel.
- [Custom Errors](https://nextjs.org/docs/pages/building-your-application/routing/custom-error?from=related) — Override and extend the built-in Error page to handle custom errors.
- [Serving Static Files](https://vercel.com/docs/platforms/multi-tenant-platforms/serving-static-files?from=related) — Serve tenant-specific static files like robots.txt, sitemap.xml, and llms.txt dynamically using route handlers.
- [Redirects](https://vercel.com/docs/routing/redirects?from=related) — Learn how to use redirects on Vercel to instruct Vercel's platform to redirect incoming requests to a new URL.
- [Custom Subpaths](https://vercel.com/docs/platforms/multi-tenant-platforms/custom-subpaths?from=related) — Host platform content on custom subpaths of customer domains while maintaining a single Next.js application.
- [Build Features](https://vercel.com/docs/builds/build-features?from=related) — Learn how to customize your deployments using Vercel's build features.
- [How to debug 404 errors](https://vercel.com/kb/guide/how-to-debug-404-errors?from=related) — Learn the systematic steps to identify and resolve 404 issues.
- [Avoiding duplicate-content SEO with vercel.app URLs and custom domains](https://vercel.com/kb/guide/avoiding-duplicate-content-with-vercel-app-urls?from=related) — Discover why search engines may treat your vercel.app URL and custom domain as separate pages, and how to consolidate ra
- [Why is my deployed project giving a 404?](https://vercel.com/kb/guide/why-is-my-deployed-project-giving-404?from=related) — Vercel 404 errors often hit healthy builds when routing metadata does not match the request path. Learn the causes and h
- [Migrate to Vercel from Netlify](https://vercel.com/kb/guide/migrate-to-vercel-from-netlify?from=related) — Migrate your website's configuration from Netlify to Vercel
- [How can I increase the limit of redirects or use dynamic redirects on Vercel?](https://vercel.com/kb/guide/how-can-i-increase-the-limit-of-redirects-or-use-dynamic-redirects-on-vercel?from=related) — Instructions on how to use Serverless Functions to handle redirects on Vercel.

Full cross-link map for this page: [/kb/guide/custom-404-page.graph.md](/kb/guide/custom-404-page.graph.md)
<!-- /docsgraph:related -->


## Zero Configuration Deployments

In most cases, creating and deploying a custom 404 page for your application will work without any additional configuration.

If you wish to create a custom 404 page, you should follow your framework's documentation.

- [Next.js: Customizing the 404 Page](https://nextjs.org/docs/advanced-features/custom-error-page)
  
- [Gatsby: Adding a 404 page](https://www.gatsbyjs.org/docs/add-404-page/)
  
- [Hugo: Custom 404 Page](https://gohugo.io/templates/404/)
  
- [Jekyll: Custom 404 Page](https://jekyllrb.com/tutorials/custom-404-page/)
  
- [Eleventy: Adding a 404 Not Found Page](https://www.11ty.dev/docs/quicktips/not-found/)
  
- [Docusaurus: Custom Pages](https://v1.docusaurus.io/docs/en/custom-pages.html)
  

## What If My Framework Doesn't Support a Custom 404 Page?

If your framework doesn't support a custom 404 page, there are a couple solutions depending on the type of framework you're using, SPA or SSG.

### Single Page Application (SPA)

These applications have a single page (`index.html`) and only support client-side routing. You can configure your router to handle the case when no route is matched, usually called a wildcard.

- [Create React App: No Match (404) with react-router-dom](https://reactrouter.com/start/framework/routing#splats)
  
- [Vue: Catch all / 404 Not found Route](https://router.vuejs.org/guide/essentials/dynamic-matching.html#catch-all-404-not-found-route)
  
- [Ember: Wildcard / globbing routes](https://guides.emberjs.com/v3.24.0/routing/defining-your-routes/#toc_wildcard--globbing-routes)
  

### Static Site Generator (SSG)

These applications generate multiple HTML pages (`index.html`, `about.html`, etc) during the [Build Step](https://vercel.com/docs/concepts/deployments/build-step).

Emit a `404.html` file to your [Output Directory](https://vercel.com/docs/concepts/deployments/configure-a-build#output-directory) and it will be served as the 404 page when a route does not match any other static file.

## What If I Need a Custom 404 API Response?

Instead of serving HTML, you may want to serve JSON or other formats when an API does not exist.

First, create a [Serverless Function](https://vercel.com/docs/concepts/functions#serverless-functions) that sets the status code to 404 and responds with a message body of your choice.

```javascript
module.exports = (req, res) => {
  res.status(404).json({ message: 'Not Found' });
};
```

Then, add an entry at the bottom of [rewrites](https://vercel.com/docs/concepts/projects/project-configuration#rewrites) in `vercel.json` to ensure that the 404 Serverless Function will execute if nothing else matches in the `/api` directory.

```json
{
  "rewrites": [{ "source": "/api/(.*)", "destination": "/api/404.js" }]
}
```

This means that visiting `/api/does-not-exist` will respond with a JSON 404 and visiting `/does-not-exist` will respond with a HTML 404 (the `404.html` from the earlier section).

## What If I Need to Name My 404 File Something Different?

If you need to assign a different file as the custom 404 page, you can add a `vercel.json` file with [routes](https://vercel.com/docs/concepts/projects/project-configuration#routes).

```json
{
  "routes": [
    { "handle": "filesystem" },
    { "src": "/(.*)", "status": 404, "dest": "/other-404.html" }
  ]
}
```