You opened out/index.html from disk
Look at the source of any exported page:
<link rel="stylesheet" href="/_next/static/css/a1b2c3.css" />
<script src="/_next/static/chunks/main-app-d4e5f6.js" async></script>
On a web server /_next/ is under the site root. On a file:/// page it is
under the root of your disk, so every stylesheet and chunk fails. Links have
the same problem: <Link href="/about"> points at file:///about.
There is no supported relative mode. assetPrefix: "./" is a common
workaround, but it only holds for top-level pages and breaks on nested routes
and client-side navigation. Serve the folder over HTTP instead:
npx serve out
GitHub Pages: _next 404s and the basePath
Two separate things break a Next export on GitHub Pages.
Jekyll eats _next. When Pages publishes from a branch it runs Jekyll,
and Jekyll skips every file and folder that starts with _. The HTML is
published; _next/ is not. Add an empty .nojekyll file to public/ so the
build copies it into out/:
touch public/.nojekyll
Deploying with the actions/deploy-pages workflow skips Jekyll, so this only
bites branch deploys.
A project site lives below the root. https://user.github.io/repo/ asks
for https://user.github.io/_next/… and gets a 404. Set the base path:
// next.config.js
module.exports = {
output: "export",
basePath: "/repo",
images: { unoptimized: true },
};
No trailing slash on basePath. It prefixes routes, <Link> targets and the
_next assets. It does not prefix paths you wrote by hand:
| Written as |
With basePath: "/repo" it requests |
Fix |
<img src="/logo.png"> |
/logo.png (404) |
src={base + "/logo.png"} |
<Image src="/logo.png" …> |
/logo.png (404) |
Static import, or prefix the string |
CSS url(/fonts/inter.woff2) |
/fonts/inter.woff2 (404) |
Relative url(../fonts/…) or prefix |
fetch("/data.json") |
/data.json (404) |
Prefix, or import the JSON at build time |
Keep the prefix in one place, for example
const base = process.env.NEXT_PUBLIC_BASE_PATH ?? "", and set it alongside
basePath. With a custom domain the site is at / again, so remove
basePath or every asset 404s.
assetPrefix is for serving _next/ from another host, such as a CDN. You
don't need it for GitHub Pages.
Refresh and deep links 404
The home page loads and client-side navigation works, but refreshing
/about or opening it from a link returns 404.
By default the export writes one file per route:
out/
├── index.html
├── about.html
└── blog/
└── first-post.html
GitHub Pages and Netlify serve about.html for /about. S3, nginx, Apache
and most CDNs look for a file or folder called about and find neither.
The portable fix is one line:
module.exports = { output: "export", trailingSlash: true };
Now the export writes about/index.html, which every static host serves for
/about/. If you'd rather keep the flat files, tell the server to try them:
| Host |
Serve about.html for /about |
| nginx |
try_files $uri $uri.html $uri/ =404; |
| Apache |
RewriteCond %{REQUEST_FILENAME}.html -f + RewriteRule |
| Firebase |
"cleanUrls": true in firebase.json |
| S3/CloudFront |
trailingSlash: true (S3 has no extension fallback) |
Don't add a catch-all rewrite to index.html here. An export has a real HTML
file per route, and a catch-all hides missing files behind a 200 (see the next
section). Dynamic segments only exist if generateStaticParams() listed them,
so /blog/new-post 404s until you rebuild.
Unexpected token '<' and ChunkLoadError
Uncaught SyntaxError: Unexpected token '<'
The browser asked for a .js chunk and got an HTML page back. Hosts set up
for single-page apps answer any missing path with index.html and a 200, so a
wrong path never shows as a 404. Check the Network tab for the chunk: if its
response is HTML, the path is wrong (the basePath cases above) or the file
wasn't deployed (the Jekyll case).
ChunkLoadError: Loading chunk 123 failed.
This one appears right after a deploy. A CDN or the browser cached the old
HTML, which references hashed chunks the new build deleted. Hard-reload
(Ctrl+Shift+R) to confirm, then serve HTML with Cache-Control: no-cache and
_next/static/ with a long immutable cache. Delete old chunks a deploy or two
later, not at once, if visitors keep tabs open.
Application error: a client-side exception has occurred
Production Next replaces the page with this one line when a component throws
in the browser. The real error is in the console. On a static export it is
usually one of these:
- Browser APIs during render.
window, localStorage or document read
at the top of a component throws during prerender or hydration. Read them
in useEffect, or load the component with
dynamic(() => import("./Chart"), { ssr: false }).
- An empty
NEXT_PUBLIC_ variable. These are inlined at build time, so a
variable set only on the host is undefined in the export, and the first
new URL(process.env.NEXT_PUBLIC_API_URL) throws. Set it in the build
environment. Variables without the prefix never reach the browser at all.
- Server features that aren't in the export. API routes, middleware,
rewrites, redirects, headers, Server Actions, ISR and cookies() all
need a running server. A fetch("/api/…") returns 404 or the host's HTML,
and the JSON parse throws. Move the call to an external API, or fetch at
build time in a Server Component.
- Hydration mismatch. Dates, random IDs or
typeof window branches that
render differently on the server and in the browser. React logs the mismatch
and re-renders on the client; an error thrown during that re-render blanks
the page.
Rebuild with source maps (productionBrowserSourceMaps: true) to see the real
file and line instead of minified chunk names.
Build errors on export
The export refuses to build rather than shipping a broken page in these cases:
next export has been removed. Next.js 14 dropped the command. Set
output: "export" in next.config.js, run next build, and read the site
from out/. Delete the next export step from your scripts and CI.
- Missing
generateStaticParams(). A dynamic route such as
app/blog/[slug]/page.tsx must list every slug at build time. Return the
full list from generateStaticParams(). In the Pages Router the equivalent
is getStaticPaths with fallback: false.
- Image Optimization isn't compatible with export. The default
next/image loader resizes on a server. Set images: { unoptimized: true },
or configure a custom loader that points at an image CDN.
useSearchParams() should be wrapped in a suspense boundary. Search
params only exist in the browser, so the page can't prerender them. Wrap the
component that reads them in <Suspense>.
Stop sending the out folder
Every file-based fix above has a ceiling: the person you send out/ to still
needs a local server, because every asset path starts at /. A build preview
works best as a URL.
Comma takes the out/ folder or a zip of it and returns one link. Assets
upload alongside the HTML with their references rewritten, so the /_next,
basePath and file:// problems don't apply, and reviewers comment on the
exact element they mean instead of sending a screenshot.
Share a Next.js static export has the steps.
Two honest caveats. Reports run in a sandboxed iframe with scripts enabled but
no same-origin access, so code that reads localStorage or cookies without a
try/catch throws there. And leave basePath unset for a preview build;
it bakes in a path the preview isn't served from.
Publish a build preview →
Related