A Next.js static export works by clicking links but gives 404 on refresh or deep links
404 Not Found (nginx) on /about after a browser refreshShort 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.
Fix it fast
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/about2Match what you see, then jump to its fix
- 1
out/ 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
Top-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
out/blog/ does not contain the id you request, so no nginx rule can find itThe dynamic page was never generated at build timeFix
- 1
What does the error look like?
404 Not Found (nginx) on /about after a browser refreshThe home page loads, but a direct link to /blog/post-1 returns 404Navigation 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/aboutConfirmed by nextjs.org
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-1Confirmed by nextjs.org
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
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
Servers
WebSocket to /_next/webpack-hmr fails when the Next.js dev server is behind nginx
WebSocket connection to 'ws://localhost/_next/webpack-hmr' failed: WebSocket is closed before the connection is established
Hot reload uses a WebSocket, and nginx does not forward the Upgrade and Connection headers unless you tell it to.
3 causes, each with a fixServers
Pages load unstyled because /_next/static files return 404 behind nginx
GET https://example.com/_next/static/chunks/main.js 404 (Not Found)
The browser asks for /_next/static/..
3 causes, each with a fixServers
A Let's Encrypt certificate did not renew with Certbot
Type: connection ... Timeout during connect (likely firewall problem)
Run sudo certbot renew --dry-run and read the Type and Detail lines.
6 causes, each with a fixServers
curl cannot connect to port 80 or 443 on a server running nginx
CURLE_COULDNT_CONNECT (7): Failed to connect() to host or proxy
Exit code 7 means the TCP connection itself failed, before any HTTP happened.
3 causes, each with a fixServers
Django returns a 500 behind Gunicorn and the traceback is nowhere
The traceback shows locally with runserver but not under Gunicorn
With DEBUG set to False, Django's default logging does not print errors to the console.
2 causes, each with a fixServers
Your website on a Google Compute Engine VM times out on port 80
The site works with curl on the VM but not from outside
A timeout, as opposed to a refusal, usually means a firewall dropped the packets.
3 causes, each with a fix