How to add a custom 404 page to a static site

Put a file named 404.html at the root of what you publish and most static hosts serve it for any missing path. Where each host looks for it, how to check it answers with a 404 and not a 200, and the two things that quietly break it — relative links and an SPA fallback.

Somebody follows an old link to your site, or types a path wrong, and gets the host's grey "Not Found" page instead of yours. You want your own page there: your header, your styles, a link back to the home page.

On almost every static host, the fix is a file named 404.html at the root of the folder you publish. Netlify, Cloudflare Pages, Vercel, GitHub Pages and Firebase look for that name without any configuration. On nginx and Apache you point the server at it in config, and Azure Static Web Apps documents the same. Then check two things the browser will not show you: that the page answers with status 404 rather than 200, and that its styles and links still work when the missing path is inside a folder.

The 30-second version

Host Where the page goes Worth knowing
Netlify 404.html in the publish folder per-section pages need a 404 rule in _redirects
Cloudflare Pages 404.html in the build output uses the nearest 404.html up the folder tree; with no root 404.html the project is treated as a single-page app
Cloudflare Workers (static assets) 404.html, plus not_found_handling = "404-page" nearest 404.html, sent with status 404
Vercel 404.html in the output directory missing paths answer with a 404, per its guide
GitHub Pages 404.html or 404.md in the publishing source 404.md needs permalink: /404.html in its front matter
Firebase Hosting 404.html in the public directory nothing extra to configure
Azure Static Web Apps responseOverrides in staticwebapp.config.json navigationFallback answers missing paths before the 404 page can
nginx error_page 404 /404.html; =200 in that line turns it into a soft 404
Apache ErrorDocument 404 /404.html a full https:// URL there sends a redirect, not a 404
dropto.run 404.html at the root of the upload root only; with the single-page-app setting on, only a 404 rule in _redirects reaches it

Of these, only the Vercel and Cloudflare Workers docs say what status the page is sent with. On the others, check it with curl (below).

A 404 page has two jobs

A not-found response is read by two audiences, and the page you design only reaches one of them.

The visitor reads the body. That is the part you are writing: it should say the page does not exist and give them somewhere to go.

Everything else — search engines, link checkers, uptime monitors — reads the status code. RFC 9110 defines 404 as the server not finding "a current representation for the target resource". Google says that it does not use the content of URLs that return a 4xx code, and that a URL already in the index that starts answering 404 is dropped.

So the page has to be yours, and the status has to stay 404. A pretty page sent with status 200 tells every crawler the broken path is a real page whose content is "not found". Google has a name for that: a soft 404, which it defines as a page telling the user it does not exist while returning 200.

Host by host

Netlify

Add 404.html to the publish folder. Netlify's docs say it "will be picked up and displayed automatically for any failed paths", with no rule needed.

For a different page per section — one per language, say — add rules with a 404 status to _redirects:

TEXT
/en/*  /en/404.html  404
/de/*  /de/404.html  404

The URL in the address bar does not change. A rule without a trailing ! never hides a file that exists, so these only answer paths that are really missing.

Cloudflare Pages

Put 404.html in the build output. Pages looks for the nearest one, walking up the folders, so /blog/404.html handles missing paths under /blog/ and /404.html handles the rest.

The catch is in the same paragraph. If there is no 404.html at the root, Pages assumes a single-page app and serves your home page for every path that does not match a file. Ship a site without the file and you do not get the default 404 page — you get your home page for every missing path. The docs name the status of neither response, so check both.

Cloudflare Workers with static assets

Set not_found_handling = "404-page" under assets in your Wrangler config. The Workers docs say that missing paths then get "the nearest 404.html file with a 404 Not Found status".

Vercel

For a static build, Vercel's guide says to emit 404.html into the output directory, where it "will be served as the 404 page when a route does not match any other static file". The same guide says a missing path then "will respond with a HTML 404".

GitHub Pages

Create 404.html or 404.md in the folder or branch you publish from. A Markdown version needs this front matter:

YAML
---
permalink: /404.html
---

Firebase Hosting

Put 404.html in the public directory. Firebase shows it whenever a request on your domain ends in a 404.

Azure Static Web Apps

Microsoft's configuration docs do not describe an automatic 404.html. What they document is pointing the 404 at a page in staticwebapp.config.json with a responseOverrides entry:

JSON
{
  "responseOverrides": {
    "404": { "rewrite": "/404.html" }
  }
}

If the same file also has a navigationFallback, that fallback answers missing paths with index.html and a 200 first. In the docs' own example, a missing file only gets a 404 when its path is listed in the fallback's exclude.

nginx

NGINX
error_page 404 /404.html;

location = /404.html {
  internal;
}

error_page serves the file through an internal redirect; the response code only changes if you ask for it with =. internal stops anyone requesting /404.html directly and getting it with a 200. Do not write error_page 404 =200 /404.html;. The =200 is the documented way to change the status, and it turns every missing page into a soft 404.

Apache

In the server config or .htaccess:

APACHE
ErrorDocument 404 /404.html

Use a path, not a full URL. Apache's docs warn that with a URL like https://example.com/404.html, "the client will not receive the original error status code, but instead will receive a redirect status code".

dropto.run

A 404.html at the root of the folder you upload is served for any missing path, with status 404. Only the root file counts — /blog/404.html is not looked up for /blog/ paths — but a 404 rule in _redirects, as on Netlify, does the per-section version. With the site set to Single-page app, missing paths get index.html instead. The root 404.html is then reached only through such a rule, because rules are checked before the fallback.

Three ways a 404 page goes wrong

It answers 200

The browser shows the same page either way, so this one is never noticed by looking. The usual causes:

  • a server rule that changes the status — nginx =200, or an Apache ErrorDocument written as a full URL, which answers the missing path with a redirect instead of a 404;
  • redirecting every missing path to the home page. For a page that is gone, Google's guidance is a 404 or a 410, with a 301 for a page that moved;
  • an SPA fallback, below.

404.html is not served at /404.html. It is served at whatever broken URL was asked for. Relative links in it are resolved against that URL: with no <base> element, the base is location.href. So <link href="style.css"> works for /oops and asks for /blog/style.css from /blog/oops, which is itself a 404. It is the same trap that breaks a whole site served from a subfolder.

Write every link in the page from the root:

HTML
<link rel="stylesheet" href="/assets/site.css">
<a href="/">Back to the home page</a>

With Vite, a 404.html dropped into public/ is copied to the output as-is, so it does not get the hashed asset names your other pages do. Root paths to files that are also in public/ are the safe choice. Generators such as Astro build 404.html for you from src/pages/404.astro.

A single-page-app fallback swallows it

A fallback rule says that every path without a file is the app. Wherever it applies, nothing is missing, and 404.html is not reached. That is true of /* /index.html 200 on Netlify, of the Cloudflare Pages default when there is no root 404.html, and of navigationFallback on Azure. The only paths still answered by the 404 page are the ones a more specific rule sends there first, such as a 404 rule placed above the catch-all, or an exclude entry on Azure. Why that rule exists is covered in why your static site 404s on refresh.

In that setup the not-found screen belongs to the app's router, and the status is always 200. Google's JavaScript SEO guide gives two ways out: send the visitor with JavaScript to a URL the server really answers with a 404, such as /not-found, or add <meta name="robots" content="noindex"> to the not-found screen with JavaScript — added only when that screen renders, since every route shares the same index.html.

Check it

BASH
curl -sI https://your-site.example/this/does/not/exist

You want a status line ending in 404 — HTTP/2 404 or HTTP/1.1 404 Not Found — and content-type: text/html. Then open the same URL in a browser and confirm the styles and images loaded. curl checks the status; the browser checks the links. Use a URL inside a folder, such as /blog/missing: a top-level one would hide the link problem.

404 or 410

RFC 9110 prefers 410 Gone when the server knows a page is gone for good. The 410 section adds that "it is not necessary to mark all permanently unavailable resources as 'gone'". The 404.html mechanism cannot produce a 410, so a 410 needs a server rule that names the path and the status, if your host gives you one. Where it does not, 404 is still a correct answer.

When not to use a 404 page

  • The page moved. A 404, however friendly, loses the visitor and the link. Send a 301 to the new address instead — redirects on a static site covers each host.
  • The whole site is one app. Keep the fallback and handle not-found in the router. Adding a 404.html at the root of a Cloudflare Pages project also switches off the single-page-app behaviour that serves your routes.
  • You want a catch-all to the home page. Served in place with a 200, it is exactly the soft 404 Google describes. Sent as a redirect, Google says that sending many old URLs to the home page "might be treated as a soft 404 error" too. Either way it hides every broken link from the people who could fix it.

Questions

Why does my 404.html show up but with status 200?

Something is rewriting the status or answering first: a =200 in nginx, or a single-page-app fallback. An Apache ErrorDocument given as a full URL looks the same in a browser, but curl shows a redirect first. Run curl -sI against a missing path to see the real status.

Why is my 404 page unstyled on some URLs but not others?

Its stylesheet link is relative, so it resolves against the broken URL. It works for a missing path at the top level and fails for one inside a folder. Make every link in the page start with /.

Can I have a different 404 page for each section?

On Cloudflare Pages and Workers, put a 404.html in the section's folder. On Netlify, add a 404 rule to _redirects for that path. Elsewhere, look for a rule with a status code — nginx error_page can be set inside a location.

Does a custom 404 page help SEO?

Not directly: Google does not use the content of a 404 response. What matters is that the status really is 404, so that broken URLs leave the index instead of being reported as soft 404s.

Should I redirect missing pages to the home page?

No. Redirect a page that moved to its new address; let a page that never existed answer 404.

This site is the product it is written about.

Drag a folder in and read the link back. No account and no card to publish.