You opened build/index.html from disk
By default CRA writes absolute paths:
<script defer="defer" src="/static/js/main.3f2a1b9c.js"></script>
On a web server /static/… means "from the site root". On a file:/// page
it means the root of your disk, so every file is ERR_FILE_NOT_FOUND. Make
the paths relative and rebuild:
// package.json
{ "homepage": "." }
Unlike Vite, CRA emits classic <script defer> tags, not module scripts, so
there is no CORS error from origin 'null'
once the paths are relative. That fixes apps without a router. Apps with one
usually stay blank — next section.
For a plain webpack config the equivalent setting is output.publicPath.
webpack 5 defaults to 'auto' (relative to the script), but most configs
copied from a tutorial set publicPath: '/' so the dev server's deep links
work — and that is the line that breaks file://.
The router renders nothing
The bundle loads, there's no error, and the root is still empty. React Router
is matching routes against window.location.pathname, and nothing matches:
| Where the build is open |
pathname the router sees |
| From disk |
/Users/you/app/build/index.html |
| GitHub Pages project site |
/repo/ |
Behind a proxy at /app/ |
/app/ |
None of those is /, so <Route path="/"> never renders. Two fixes:
// Sub-path host: tell the router where it lives
<BrowserRouter basename={process.env.PUBLIC_URL}>
process.env.PUBLIC_URL is derived from homepage, so the two can't drift.
// Opened from disk, or a path you don't control: hash routing
import { HashRouter } from "react-router-dom";
<HashRouter>
With hash routing URLs look like index.html#/settings. The browser never
treats the part after # as a path, so the router works from disk, on any
sub-path and on hosts with no fallback. A catch-all <Route path="*"> that
renders a "not found" message is worth adding either way: a wrong path becomes
a visible page instead of a white one.
GitHub Pages and other sub-paths
A project site lives at https://user.github.io/repo/, but the default build
asks for https://user.github.io/static/js/… and gets a 404.
// package.json
{
"homepage": "https://user.github.io/repo",
"scripts": { "predeploy": "npm run build", "deploy": "gh-pages -d build" }
}
Then add basename={process.env.PUBLIC_URL} from the section above. Two more
things that trip people on Pages specifically:
- Publish
build/, not the repo root. The source public/index.html has
no script tags — CRA injects them at build time — so deploying it gives a
blank page with no error at all.
- Custom domain. With
www.example.com pointed at the site, the app lives
at / again. Change homepage to the domain or ".", or every asset 404s.
The same rules apply to GitLab Pages (also publish to public/ — see
GitLab Pages report 404s), an S3 prefix, or
any reverse proxy that mounts the app below /.
"Uncaught SyntaxError: Unexpected token '<'"
Uncaught SyntaxError: Unexpected token '<' (at main.3f2a1b9c.js:1:1)
The browser asked for a .js file and got HTML, whose first character is
<. A host configured for single-page apps answers any missing path with
index.html and a 200, so a wrong path never shows up as a 404. The usual
reasons:
- Relative paths plus a nested route. With
"homepage": ".", a refresh
on /users/42 asks for /users/static/js/main.js. Use an absolute
homepage with BrowserRouter, or hash routing.
- Wrong
homepage or publicPath — the GitHub Pages case above, with a
fallback hiding the 404.
- A stale
index.html. A CDN or the CRA service worker (serviceWorker.register()
in older templates) cached the old entry page, which references hashed files the
new deploy deleted. Hard-reload (Ctrl+Shift+R) to confirm, then serve
index.html with Cache-Control: no-cache and unregister the worker. The
same mismatch, hit by a lazy import(), is ChunkLoadError.
Refresh or a deep link 404s
The home page loads, links work, but refreshing /settings returns 404. The
route only exists in JavaScript; the server looks for a file called
settings and has none.
| Host |
Fallback to index.html |
| GitHub Pages |
Copy build/index.html to build/404.html after the build |
| Netlify |
public/_redirects: /* /index.html 200 |
| Vercel |
vercel.json: {"rewrites":[{"source":"/(.*)","destination":"/"}]} |
| Cloudflare Pages |
Automatic when there is no 404.html at the root |
| nginx |
try_files $uri $uri/ /index.html; |
serve |
npx serve -s build — the -s is the fallback |
| webpack dev server |
devServer: { historyApiFallback: true } |
Where you can't configure the server, use HashRouter.
An environment variable is undefined
Create React App replaces process.env.* when npm run build runs, and only
for names that start with REACT_APP_ (plus NODE_ENV and PUBLIC_URL):
process.env.REACT_APP_API_URL; // baked into the bundle
process.env.API_URL; // undefined, always
The classic blank page: .env.local exists on your laptop, the CI build
doesn't have it, the value is undefined, and the first component that calls
a method on it throws. There is no runtime to set it in afterwards — set it in
the build environment, and rebuild.
Plain webpack 5 has no process in the browser at all. Code — yours or a
dependency's — that reads process.env.X or uses Buffer throws
process is not defined on the first render:
// webpack.config.js
const webpack = require("webpack");
module.exports = {
plugins: [
new webpack.DefinePlugin({ "process.env.API_URL": JSON.stringify(process.env.API_URL) }),
new webpack.ProvidePlugin({ Buffer: ["buffer", "Buffer"], process: "process/browser" }),
],
};
Upgrading react-scripts from 4 to 5 is the same webpack 5 change, which is
why an app can go blank with no code change of your own.
Two more that only show up in the build
- A crash during the first render. Without an error boundary, any
exception in a top-level component unmounts the whole tree — white screen.
Minified, the stack trace is useless; CRA writes source maps by default, so
serve the build with
npx serve -s build and the console points at your
real file and line.
- Case-sensitive imports.
import Header from "./header" finds
Header.js on macOS and Windows, then fails on the Linux CI runner.
Create React App itself was deprecated in February 2025. None of the fixes
above need a migration, but if you are touching the build config anyway,
Vite's equivalents are in the Vite version of this page.
Stop sending the build folder
Every file-based fix above has a ceiling: the person you send the build to
still needs the right folder, the right path and, often, a local server. A
build preview works best as a URL.
Comma takes the build/ folder or a zip of it and returns one link. Assets
upload alongside the entry page with their references rewritten, so the
absolute-path and file:// problems disappear, and reviewers comment on the
exact element they mean instead of sending a screenshot. The same flow works
for any static build — see share a Vite build for the
API call to run from CI.
Two honest caveats. Reports run in a sandboxed iframe with scripts enabled
but no same-origin access, so code that touches localStorage or cookies
without a try/catch throws there — guard it. And build the preview with
HashRouter so every view has a working link.
Publish a build preview →
Related