Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

A Next.js static export works by clicking links but gives 404 on refresh or deep links

Error404 Not Found (nginx) on /about after a browser refresh

Short answer

A static export writes one HTML file per route, such as about.html. nginx only finds it if the config maps /about to that file, so a refresh or a pasted deep link gives 404 while in-app clicks still work. Add a try_files rule that tries .html, or build with trailingSlash: true. Dynamic routes also need generateStaticParams.

  • Applies to Next.js 15, Next.js 16, nginx 1.26, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    List what the export actually produced, then compare it with the URL that fails. If the file is /about.html but the request is /about, the nginx mapping is the problem.

    find out -maxdepth 2 -name "*.html" | sort
    curl -I http://127.0.0.1/about
  2. 2Match what you see, then jump to its fix

    1. 1out/ contains about.html (not about/index.html), and the request for /about gets nginx's own 404nginx has no rule that maps /about to about.htmlFix
    2. 2Top-level pages work, but /blog/post-1 fails even with the try_files rule aboveA dynamic route such as /blog/[id] needs its own rewriteFix
    3. 3out/blog/ does not contain the id you request, so no nginx rule can find itThe dynamic page was never generated at build timeFix

What does the error look like?

  • 404 Not Found (nginx) on /about after a browser refresh
  • The home page loads, but a direct link to /blog/post-1 returns 404
  • Navigation with next/link works, a hard reload of the same URL does not

Cause 1 of 3

nginx has no rule that maps /about to about.html

1Check

With the default trailingSlash: false, every route is emitted as a flat .html file. A bare location / with the default index logic looks for a file or a directory named about, finds neither and answers 404.

ls out/
grep -R -n "try_files" /etc/nginx/sites-enabled/

2Fix

Let nginx try the exact path, then the path plus .html, then a directory. Point root at the out folder.

server {
  listen 80;
  server_name example.com;
  root /var/www/out;

  location / {
      try_files $uri $uri.html $uri/ =404;
  }
}

3Verify

Test the config, reload nginx and request the deep link again.

sudo nginx -t && sudo systemctl reload nginx
curl -I http://127.0.0.1/about

Confirmed by nextjs.org

Did this fix it?

Cause 2 of 3

A dynamic route such as /blog/[id] needs its own rewrite

1Check

With trailingSlash: false the export contains /blog/post-1.html. The docs give a separate rewrite for such a folder. Check that the file exists under out/blog/ and that the location block exists.

ls out/blog/
grep -n "location /blog/" /etc/nginx/sites-enabled/*

2Fix

Add a rewrite for the dynamic folder, or avoid the rewrite by building with trailingSlash: true, which emits /blog/post-1/index.html.

location /blog/ {
    rewrite ^/blog/(.*)$ /blog/$1.html break;
}

// next.config.js (alternative)
module.exports = {
  output: 'export',
  trailingSlash: true,
}

3Verify

Rebuild if you changed next.config.js, copy out/ to the server, reload nginx and open the deep link.

npm run build
curl -I http://127.0.0.1/blog/post-1

Confirmed by nextjs.org

Did this fix it?

Cause 3 of 3

The dynamic page was never generated at build time

1Check

A static export cannot render a dynamic route on demand. A route without generateStaticParams(), or one with dynamicParams: true, is not supported, so only the ids returned at build time exist as files.

ls out/blog/

2Fix

Return every id you need from generateStaticParams() in the route, then rebuild.

// app/blog/[id]/page.tsx
export async function generateStaticParams() {
  return [{ id: 'post-1' }, { id: 'post-2' }]
}

3Verify

After rebuilding, each id appears as a file in out/blog/.

npm run build
ls out/blog/

Confirmed by nextjs.org

Did this fix it?

How do I stop it coming back?

  • Keep the nginx try_files rule in the same repository as next.config.js, so a change to trailingSlash updates both.
  • After every build, request a deep link with curl instead of only clicking through the site.
  • Remember that rewrites, redirects and headers in next.config.js do nothing in a static export; put them in nginx.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.