Next.js static export shows a blank or unstyled page

next dev works. next build with output: 'export' finishes and writes out/. Then the exported site is a white screen, plain unstyled text, or a page whose links all 404.

A static export fails differently from a single-page app. Next prerenders every page to HTML, so you usually see something: the text without its CSS. A fully blank page means the content is rendered only on the client, and the JavaScript never ran. Open the console (F12 → Console) and the Network tab before you change anything. For other frameworks see Vite, React and Angular.

Match the symptom to the cause

What you see Cause Section
Unstyled text, ERR_FILE_NOT_FOUND for /_next/static/… Opened out/index.html from disk Opened from disk
Unstyled on GitHub Pages, 404 for every /_next/… file Jekyll skipped _next, or no basePath GitHub Pages
Styled home page, broken images or fonts below /repo/ Hardcoded / paths ignore basePath GitHub Pages
/about 404s on refresh or a direct link about.html without trailingSlash Refresh and deep links 404
Uncaught SyntaxError: Unexpected token '<' A chunk request got index.html back Unexpected token and chunks
ChunkLoadError: Loading chunk … failed after a deploy Cached HTML points at deleted chunks Unexpected token and chunks
Application error: a client-side exception has occurred A component threw in the browser Application error
Build error: next export has been removed Next 14 dropped the command Build errors on export
Build error: missing generateStaticParams() Dynamic route with no list of pages Build errors on export
Build error: Image Optimization … not compatible with export next/image default loader needs a server Build errors on export

Check it away from your machine

See your page the way someone else will

Drop the HTML or paste it. It opens on a shareable page, so you can confirm the fix works for a reader, not just on your laptop.

Your file is read in this tab and nothing is uploaded until you publish. Creating an account is free, and reading a shared link never needs one.

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

Have an HTML report to share? Publish it free and send one link people can comment on.