Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Angular routes return 404 from nginx when you refresh or open a link

Error404 Not Found nginx

Short answer

Angular routes like /users/42 are not files, so nginx looks for them on disk and returns 404. Tell nginx to fall back to index.html with try_files. Also make root point at dist/your-app/browser, where the build puts index.html, and reload nginx after the change.

  • Applies to Angular 20, nginx 1.26, Docker 27
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Request the home page and a deep link with curl. If / works and the deep link is 404, you need the fallback. If / fails too, the root path is wrong.

    curl -I http://localhost/
    curl -I http://localhost/users/42
  2. 2Match what you see, then jump to its fix

    1. 1/ returns 200, a deep link returns 404nginx has no fallback to index.htmlFix
    2. 2Even / returns 404 or an nginx 403root points at dist/your-app instead of dist/your-app/browserFix
    3. 3The fix is in the file, behavior is unchangedThe config was changed but nginx never reloaded itFix

What does the error look like?

  • 404 Not Found nginx
  • The home page loads, but refreshing /some/route shows an nginx 404

Cause 1 of 3

nginx has no fallback to index.html

1Check

Angular's deployment guide says a routed app needs the server to return index.html for paths it does not have, because the browser bypasses the Angular router on refresh. Look at your location block.

grep -rn -A3 "location /" /etc/nginx/conf.d/ /etc/nginx/sites-enabled/ 2>/dev/null

2Fix

Make the last try_files parameter the index page. nginx then redirects internally to it when no file matches.

server {
    listen 80;
    root /usr/share/nginx/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

3Verify

Test the config, reload, and request the deep link.

nginx -t && nginx -s reload
curl -I http://localhost/users/42

Confirmed by nginx.org

Did this fix it?

Cause 2 of 3

root points at dist/your-app instead of dist/your-app/browser

1Check

ng build writes to dist/your-app, and for static hosting the folder to serve is dist/your-app/browser. In Docker, the COPY line must copy that folder.

ls dist/my-app
ls dist/my-app/browser/index.html

2Fix

Copy or point to the browser folder.

# Dockerfile (final stage)
COPY --from=build /app/dist/my-app/browser /usr/share/nginx/html

3Verify

Rebuild the image, run it and request the home page.

docker build -t my-app .
docker run --rm -p 8080:80 my-app
curl -I http://localhost:8080/

Confirmed by angular.dev

Did this fix it?

Cause 3 of 3

The config was changed but nginx never reloaded it

1Check

Changes to the configuration file are not applied until nginx is reloaded or restarted. In Docker the file must also be inside the running container.

docker exec my-app nginx -T | grep -n "try_files"

2Fix

Reload nginx. If the file is baked into the image, rebuild and recreate the container.

docker exec my-app nginx -s reload

3Verify

Request a deep link again.

curl -I http://localhost:8080/users/42

Confirmed by nginx.org

Did this fix it?

How do I stop it coming back?

  • Keep the nginx config in the repository and copy it in the Dockerfile.
  • Add a deep-link curl check to the deploy pipeline.
  • Serve the browser output folder only, not the whole dist directory.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.