Angular build shows a blank page

ng serve works. ng build finishes without an error. Then the built app is a white screen and <app-root> stays empty.

Open the console (F12 → Console) before you change anything. A blank Angular build almost always leaves one message, and that message names the cause. This page covers the Angular CLI application builder (Angular 17 and later) and notes where older browser builder projects differ. For other frameworks, see Vite and React.

Match the console message to the cause

What the console or Network tab shows Cause Section
ERR_FILE_NOT_FOUND for main-….js, styles-….css Opened from disk; <base href="/"> Opened index.html from disk
Access to script … from origin 'null' has been blocked by CORS Module scripts on file:// Opened index.html from disk
Host shows 404 or a file list at the site root Deployed dist/<app>, not dist/<app>/browser The browser/ folder
404 for https://user.github.io/main-….js Base href doesn't include the sub-path GitHub Pages and sub-paths
Expected a JavaScript module script … MIME type of "text/html" The bundle request got index.html back MIME type text/html
NG04002: Cannot match any routes. URL Segment: 'index.html' Router matched nothing The router matches nothing
Home page fine, any other URL 404 on refresh Server has no SPA fallback Refresh 404
NG0908: In this configuration Angular requires Zone.js Zone.js dropped from polyfills Errors that only the build has
Blank, with an error from an APP_INITIALIZER or config fetch Bootstrap waited on a request that failed Errors that only the build has

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 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

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