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

## Related Documentation

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

## More Vercel Functions guides

- [Optimize Runtime Cache on Vercel](/kb/guide/optimize-runtime-cache-reads-on-vercel): Diagnose rising Runtime Cache usage, trace reads to tags and code paths, and reduce avoidable reads while checking write cost and origin traffic.
- [How to stop Vercel Functions from timing out](/kb/guide/what-can-i-do-about-vercel-serverless-functions-timing-out): Vercel Functions that time out usually trace back to a few causes. Learn how Fluid Compute fixes most of them and how to handle the edge cases.
- [The Complete Guide to Vercel Connect](/kb/guide/vercel-connect): Use Vercel Connect to call provider APIs like Slack, GitHub, Linear, Microsoft, Discord, Snowflake, and Salesforce from your agents and services with short-lived, scoped tokens instead of long-lived secrets.

## 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)