# Angular Build Shows a Blank Page — base href, dist/browser and the Router

Canonical: https://commareports.com/fix/angular-build-blank-page
Published: 2026-11-19

> `ng serve` works, but the `ng build` output is a white screen. The console message behind each cause — `<base href>`, module scripts on file://, the dist/<app>/browser folder, `NG04002: Cannot match any routes`, refresh 404s, NG0908 — and the fix for each.

# 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](/fix/vite-build-blank-page) and
[React](/fix/react-build-blank-page).

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

## You opened index.html from disk

Every Angular project starts with this line in `src/index.html`:

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

```bash
ng build --base-href ./
```

It doesn't fix the page. The CLI emits module scripts:

```html
<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'](/fix/cors-error-file-origin-null). There's no
build flag that turns module output off. Serve the folder over HTTP instead:

```bash
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.

```bash
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:

```bash
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](/fix/gitlab-pages-report-404)), 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:

```ts
// app.config.ts (standalone)
provideRouter(routes, withHashLocation());
```

```ts
// 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:

```ts
{ 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](/share-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 →](https://commareports.com/)**

### Related

- [Vite build shows a blank page](/fix/vite-build-blank-page)
- [React (Create React App, webpack) build shows a blank page](/fix/react-build-blank-page)
- [Next.js static export shows a blank or unstyled page](/fix/nextjs-static-export-blank-page)
- [CORS error from origin 'null'](/fix/cors-error-file-origin-null)
- [ERR_FILE_NOT_FOUND in Chrome](/fix/err-file-not-found)
- [GitLab Pages report 404s](/fix/gitlab-pages-report-404)
- [The localhost link doesn't work for others](/fix/localhost-link-doesnt-work-for-others)
- [Share an Angular build](/share-angular-build)
