You opened index.html from disk
Every Angular project starts with this line in src/index.html:
<base href="/" />
On a web server / is the site root. On a file:/// page it is the root of
your disk, so main-….js, polyfills-….js and styles-….css all come back
as ERR_FILE_NOT_FOUND. Rebuilding with a relative base fixes the paths:
ng build --base-href ./
It doesn't fix the page. The CLI emits module scripts:
<script src="main-HXR3LDNJ.js" type="module"></script>
Chrome and Edge treat every file:// page as a unique origin and refuse to
load module scripts from it, so the console swaps one error for a
CORS error from origin 'null'. There's no
build flag that turns module output off. Serve the folder over HTTP instead:
npx http-server dist/my-app/browser -p 8080
Older projects on the browser builder had the same two problems, plus a
--deploy-url flag that is now deprecated. Use --base-href alone.
You deployed the wrong folder
Angular 17 moved new projects to the application builder, and it writes a
deeper tree:
dist/my-app/
├── browser/ ← deploy this
│ ├── index.html
│ ├── main-HXR3LDNJ.js
│ └── styles-5INURTSO.css
├── server/ ← only with SSR
└── 3rdpartylicenses.txt
A deploy script written for Angular 16 uploads dist/my-app, the host finds
no index.html at its root, and you get a 404, an empty page or a directory
listing. Point the upload at dist/my-app/browser. On Firebase that is
"public": "dist/my-app/browser" in firebase.json; on Netlify it is the
publish directory.
If SSR is on, the browser folder's entry page is index.csr.html, not
index.html, and a static host won't serve it by default. Either run the
Node server from server/, or prerender the routes so static index.html
files exist ("outputMode": "static" in Angular 19 and later).
GitHub Pages and other sub-paths
A project site lives at https://user.github.io/repo/, but a default build
asks for https://user.github.io/main-….js and gets a 404.
ng build --base-href /repo/
Keep the trailing slash: /repo without it makes the browser resolve assets
against /. Or let angular-cli-ghpages handle both the base href and the
upload:
ng add angular-cli-ghpages
ng deploy --base-href=/repo/
Two more Pages traps:
- Custom domain. With
www.example.com pointed at the site, the app lives
at / again. Drop --base-href /repo/ or every bundle 404s.
- Jekyll. Pages runs Jekyll on branch deploys and skips files that start
with
_. Add an empty .nojekyll file to the output (angular-cli-ghpages
does it for you).
The same rule applies to GitLab Pages (see
GitLab Pages report 404s), an S3 prefix, or a
reverse proxy that mounts the app below /. The base href must name the path
the browser sees.
"Expected a JavaScript module script … MIME type of text/html"
Failed to load module script: Expected a JavaScript module script but the
server responded with a MIME type of "text/html".
This is Angular's version of React's Unexpected token '<'. The browser asked
for main-….js and got an HTML page. 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:
- The base href doesn't match the mount path — the sub-path case above,
with a fallback hiding the 404.
- The wrong folder was deployed — the browser/ case above.
- A stale
index.html. A CDN or the Angular service worker
(@angular/pwa) cached the old entry page, which references hashed bundles
the new deploy deleted. Hard-reload (Ctrl+Shift+R) to confirm, then serve
index.html with Cache-Control: no-cache. With the service worker, make
sure ngsw.json was deployed alongside the build.
The router matches nothing
The bundles load, then the console says:
ERROR RuntimeError: NG04002: Cannot match any routes. URL Segment: 'index.html'
The router reads window.location.pathname, and the page's real path is not
one of your routes:
| Where the build is open |
Path the router sees |
…/browser/index.html |
/index.html |
| A host without a base |
/repo/ while routes expect / |
| A link someone shared |
/index.html#/reports with path routing off |
Where you can't control the path, switch to hash routing:
// app.config.ts (standalone)
provideRouter(routes, withHashLocation());
// app.module.ts (NgModule)
RouterModule.forRoot(routes, { useHash: true });
URLs then look like index.html#/settings, and the browser never treats the
part after # as a path. Add a wildcard as the last route either way, so an
unknown path renders something instead of nothing:
{ path: "**", redirectTo: "" }
Refresh or a deep link 404s
The home page loads and links work, but refreshing /settings returns 404.
The route only exists in the client; the server looks for a file called
settings and has none.
| Host |
Fallback to index.html |
| GitHub Pages |
Copy index.html to 404.html (angular-cli-ghpages does it) |
| Netlify |
_redirects in the output: /* /index.html 200 |
| Vercel |
vercel.json: {"rewrites":[{"source":"/(.*)","destination":"/"}]} |
| Firebase Hosting |
"rewrites": [{ "source": "**", "destination": "/index.html" }] |
| nginx |
try_files $uri $uri/ /index.html; |
| Apache |
FallbackResource /index.html |
To ship _redirects or 404.html with the build, list the file under
"assets" in angular.json so the CLI copies it into browser/. Where you
can't configure the server, use hash routing.
Errors that only the build has
- NG0908: Angular requires Zone.js. An upgrade moved polyfills from
polyfills.ts into angular.json, and zone.js didn't make the move. Add
"polyfills": ["zone.js"] to the build target, or bootstrap with
provideZonelessChangeDetection() if the app is meant to run without
zones.
- A failed
APP_INITIALIZER. Apps that fetch assets/config.json before
bootstrap stay blank if that request fails, and on a sub-path it does when
the URL starts with /. Fetch assets/config.json without the leading
slash so it resolves against the base href, and catch the error so a
missing config shows a message instead of nothing.
- The production environment file.
fileReplacements in angular.json
swaps environment.ts for environment.prod.ts only in the configuration
that lists it. A missing entry ships the development API URL, and the first
request fails.
- Minified errors. Production builds strip messages down to codes like
NG0100. Look the code up at angular.dev/errors, or build with
ng build --configuration development to see the full message and source
maps.
- Case-sensitive imports.
./Header.component finds
header.component.ts on macOS and Windows, then fails on the Linux CI
runner.
Stop sending the dist folder
Every file-based fix above has a ceiling: the person you send the build to
still needs the right folder, the right base href and a local server, because
module scripts never run from file://. A build preview works best as a URL.
Comma takes the browser/ folder or a zip of it and returns one link. Assets
upload alongside index.html, so the base-href and file:// problems don't
apply, and reviewers comment on the exact element they mean instead of sending
a screenshot. Share an Angular build has the CLI and
CI 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 build the preview with hash routing so every
view has a working link.
Publish a build preview →
Related