---
title: Custom 404 Page
description: Create a custom 404 page and deploy with Vercel.
url: "https://vercel.com/kb/guide/custom-404-page"
published: 2025-11-03
last_updated: 2026-07-16
authors: Steven Salat
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---

## 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" }
  ]
}
```

## More Vercel Functions guides

- [Next.js on Vercel vs Webflow Cloud](/kb/guide/next-js-on-vercel-vs-webflow-cloud): Compare running Next.js on Vercel Functions with Fluid compute against Webflow Cloud on Cloudflare Workers. Learn how Next.js feature support, runtimes, storage, pricing, and developer experience differ so you can choose the right platform.
- [Migrate a Next.js app from Webflow Cloud to Vercel](/kb/guide/migrate-a-next-js-app-from-webflow-cloud-to-vercel): Move your Next.js app from Webflow Cloud to Vercel: remove the OpenNext Cloudflare adapter, drop the base path, map storage bindings to Vercel Blob, Redis, and Postgres, and deploy with Git or the vercel CLI.
- [Vercel vs Webflow Cloud](/kb/guide/vercel-vs-webflow-cloud): Compare Vercel and Webflow Cloud for deploying Next.js and Astro apps, including runtime, framework support, storage, pricing, and where your code runs.