Fix Next.js Static Export 404 Errors on Refresh

A Next.js static export returning 404 on refresh usually means the requested URL does not map to an exported HTML file on the host. Verify the generated route, upload location, slash convention, and directory index behavior. Dynamic routes must have their supported paths generated during the build.

Why can a link work while a direct visit fails?

In an illustrative shared-hosting release, clicking from the homepage to a service appears to work, but opening that service URL in a fresh tab fails. Client navigation and a direct document request use different resources. A working transition does not prove that Apache can resolve the route to the correct HTML file.

Check the response in a fresh browser session and with an HTTP request. Record the final URL, redirect chain, status, content type, and page title. Distinguish a real 404 from a homepage served with HTTP 200. The second behavior can look functional while confusing search engines and hiding broken links.

Step 1: prove that the page exists in the export

Inspect the project's build configuration and documented export command. With trailing slashes enabled, a route such as /services/example/ normally maps to an output directory containing index.html. Without that convention, the generated file layout differs. Inspect the actual output rather than assuming a previous project's layout applies.

If the file is absent locally, fix generation before editing server rewrites. For an App Router dynamic segment, ensure the build supplies the required parameters. A static host cannot generate an unknown blog slug on demand. Keep real missing URLs as 404s instead of substituting the homepage.

Step 2: align export configuration and dynamic parameters

The following examples show the configuration relationship. The post loader is illustrative and must return your own published records. Preserve existing project settings when adding export options; do not replace security, image, or deployment configuration with this small fragment.

// next.config.ts
const nextConfig = {
  output: "export",
  trailingSlash: true,
};
export default nextConfig;

// app/blog/[slug]/page.tsx
export async function generateStaticParams() {
  const posts = await getPublishedPosts();
  return posts.map(post => ({ slug: post.slug }));
}

Use the APIs supported by the installed Next.js version and review its bundled documentation when behavior differs. Features requiring a live server, such as request-time handlers or runtime-only route generation, need a compatible hosting model. A rewrite cannot turn a file server into a Next.js application server.

Step 3: upload the contents to the correct website root

Confirm that the selected hosting directory belongs to the intended domain before changing files. Back up changed existing files and preserve unrelated applications, API directories, and older hashed assets still referenced by cached pages. Upload the export's contents, including hidden hosting configuration files, rather than nesting the output folder one level too deep.

Publish supporting assets before HTML so new pages do not reference files that have not arrived. Verify the upload retains nested directories. A transfer tool that skips empty ancestor directories or dotfiles can produce a partial release even when its top-level progress indicator reports completion.

Step 4: configure directory indexes and genuine missing pages

For a trailing-slash export on Apache or compatible LiteSpeed hosting, the following directives illustrate directory index and error-document behavior. They assume the host allows the relevant overrides and that 404.html exists. Test the configuration on your host; unsupported directives can produce an HTTP 500.

DirectoryIndex index.html
ErrorDocument 404 /404.html

# Do not rewrite every unknown URL to the homepage.
# Keep the export's real directory structure in the document root.

A slashless request may redirect to a directory URL; verify that its destination matches the page's canonical URL. If you use a different file layout or a non-Apache host, use that server's supported route mapping. Avoid stacking several copied catch-all rules until one happens to hide the symptom.

Step 5: verify documents, assets, and crawler signals

1. Open the homepage and several nested routes directly. Confirm HTTP 200 and the correct page title for each.
2. Reload each nested page and test a new browser session. Confirm that the request does not depend on previous client navigation.
3. Request a deliberately nonexistent URL. It must return HTTP 404 with a useful error page.
4. Inspect referenced scripts, styles, fonts, and images for missing files or incorrect content types.
5. Check canonical URLs, sitemap entries, and robots rules against the published slash convention.
6. Inspect cache behavior after release so stale HTML and missing new assets are not mistaken for a routing failure.

If the route works locally but not remotely, compare the published file bytes or checksums with the release artifact. If both fail, return to generation and preview configuration. This split prevents a hosting investigation from masking an export problem. Keep the release checksum and backup location in the deployment record.

Does a catch-all homepage rewrite help SEO?

No. Serving the homepage for every unknown path hides missing routes and gives visitors the wrong content. Search engines need the requested page or an accurate error response. A route that was intentionally moved should use a specific permanent redirect to its relevant replacement rather than a global fallback.

For example, a retired service URL can redirect to the current service page while a mistyped blog slug remains a genuine 404. Test both cases after deployment. Also verify that an error page does not inherit a canonical URL claiming to be the missing article. Keep redirect mappings explicit and review them when changing published URLs.

For missing configuration in an otherwise valid page, follow the production environment-variable guide. Our web application development service includes scoped release improvements. Share the failing URL and hosting model with the export layout and response status so the next check is concrete.

Official references and further reading

Next.js: static export support and deployment

Next.js: generateStaticParams

Apache: DirectoryIndex