Angular routes return 404 from nginx when you refresh or open a link
404 Not Found nginxShort 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.
Fix it fast
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/422Match what you see, then jump to its fix
What does the error look like?
404 Not Found nginxThe 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/null2Fix
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/42Confirmed by nginx.org
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.html2Fix
Copy or point to the browser folder.
# Dockerfile (final stage)
COPY --from=build /app/dist/my-app/browser /usr/share/nginx/html3Verify
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
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 reload3Verify
Request a deep link again.
curl -I http://localhost:8080/users/42Confirmed by nginx.org
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
Related fixes
Servers
A Next.js static export works by clicking links but gives 404 on refresh or deep links
The home page loads, but a direct link to /blog/post-1 returns 404
A static export writes one HTML file per route, such as about.html.
3 causes, each with a fixServers
Docker php image has no php.ini and my edits do not stay
A setting changed in php.ini inside the container is gone after the container is recreated
The official php image ships php.ini-development and php.ini-production but no active php.ini.
2 causes, each with a fixServers
The MinIO Console will not work behind an nginx proxy: no login, 403 on the WebSocket, or repeated disconnects
The Console UI shows repeated disconnects
Behind a proxy the MinIO Console needs three things.
4 causes, each with a fixServers
nginx returns 403 and logs directory index is forbidden
directory index of "/usr/share/nginx/html/" is forbidden
nginx got a request for a folder, found none of the index files it was told to look for, and listing the folder is off by default.
3 causes, each with a fixServers
nginx in a container returns 502 with 'connection refused' to another container
502 Bad Gateway
Inside a container, localhost is the container itself.
4 causes, each with a fixServers
The nginx container serves the default page or 404 because /usr/share/nginx/html has no app files
requests for your pages return 404 Not Found
The official nginx image serves whatever sits in /usr/share/nginx/html.
3 causes, each with a fix