---
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
search_with_vercel_cli: npx vercel@latest kb search "<query>"
read_with_vercel_cli: "npx vercel@latest kb inspect custom-404-page"
---

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

## Related Documentation

- [Vercel Functions](/docs/functions)
- [Next.js](/docs/frameworks/full-stack/nextjs)

## More Vercel Functions guides

- [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.
- [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.
- [Astro on Vercel vs Webflow Cloud](/kb/guide/astro-on-vercel-vs-webflow-cloud): Compare running Astro on Vercel Functions with Fluid compute against Webflow Cloud on Cloudflare Workers. Learn how Astro feature support, runtimes, storage, pricing, and developer experience differ so you can choose the right platform.

## Reference Architecture

Choose a stack and work through the decisions behind it, with curated documentation, guides, templates, and courses to help you build.

- [Agent stack](/kb/architecture/agents): Build and operate agents with models, tools, and durable workflows.
- [Web applications](/kb/architecture/web): Choose rendering, data, authentication, and caching approaches.
- [Backends](/kb/architecture/backends): Choose a runtime, connect services, and run background work.

[Browse all stacks](/kb/architecture)

## Build with prompts

Build an app, extend an agent, or improve your project with ready-to-use prompts for your coding agent.

[Browse the prompt library](/kb/prompts) · [Read the Markdown index](/kb/prompts.md)

## Search guides from your terminal

Search the Knowledge Base and read guides as Markdown with the Vercel CLI. No login required.

```bash
# Find guides by keyword
npx vercel@latest kb search "rewrites and redirects"
npx vercel@latest kb search "AI SDK streaming"

# Show the latest guides
npx vercel@latest kb

# Print a guide as Markdown, by slug or URL
npx vercel@latest kb inspect <guide>
```