VPS Tutorials
Vue and React refresh 404s on Nginx: routes, assets and try_files
If the homepage works but a deep-link refresh fails, separate SPA routes, static assets and APIs. Configure Nginx fallback and diagnose JavaScript receiving HTML or incorrect subdirectory paths.

Your Vue or React site loads at its homepage, and navigating from the menu to /dashboard works, but refreshing that URL produces an Nginx 404. The browser's route and the server's file path are usually being handled differently. Another common failure is a 200 response containing HTML where JavaScript was expected, leaving a blank page.
This guide applies to a built static single-page application served by Nginx. Inspect requests, files and matching rules before adding a page fallback. Treat APIs and static assets separately. A server-rendered Next.js or Nuxt application needs a different deployment configuration.
Open the browser's Network panel, refresh the affected page, and inspect the document, JS/CSS and API requests separately. The error text visible on the page is not enough to choose a configuration change.
| Request result | Check first | Correct handling |
|---|---|---|
Document /dashboard returns 404, but in-app navigation works | History-mode route fallback | Serve the entry HTML so the frontend can resolve the route |
/assets/app-xxx.js returns 404 | Build output, asset path and old caches | Serve the actual file; do not substitute the homepage for JS |
| JS returns 200 with an HTML body | Fallback is catching asset requests | Return a genuine 404 for missing assets |
/api/users returns the homepage | A page rule is catching the API | Restore its separate API route or reverse proxy |
The Vue Router history-mode guide explains why internal navigation differs: the browser handles it, but a direct request for a deep URL still needs the application entry document. Serving that document does not prove that the frontend route exists.
For Vite's default output, run the project's existing build command and confirm that dist/index.html and all referenced assets were uploaded. The Vite deployment documentation specifies dist as the default output directory. It also notes that vite preview is for local preview, not a production server.
Assume the output is installed at /srv/www/app/dist and the domain is app.example.com. Inspect the effective configuration and files:
sudo nginx -T
ls -l /srv/www/app/dist/index.html
ls -l /srv/www/app/dist/assets/
Confirm the matching server_name, HTTP/HTTPS site and root. A panel such as Baota or 1Panel may generate the configuration and overwrite manual changes. The output of nginx -T can include internal addresses; redact it before sharing.
Check filename case as well. Logo.png working locally does not mean Linux will serve it as logo.png. With containerized Nginx, inspect the files inside the container: host files alone do not prove the mount is correct. See Compose data and mount troubleshooting.
The following HTTP example is for a dedicated domain deployed at its root, without a backend API. Merge the relevant rules into an existing HTTPS server and preserve its certificates. If you already have an API, retain its real proxy rules; do not replace them with the placeholder 404 below.
server {
listen 80;
server_name app.example.com;
root /srv/www/app/dist;
index index.html;
location = /index.html {
try_files $uri =404;
add_header Cache-Control "no-cache" always;
}
location ^~ /assets/ {
try_files $uri =404;
}
location ^~ /static/ {
try_files $uri =404;
}
location = /api {
return 404;
}
location ^~ /api/ {
return 404;
}
location / {
try_files $uri $uri/ /index.html;
}
}
When /dashboard cannot find a real file, it internally redirects to /index.html. A separate entry-file rule returns 404 if that entry is missing too, preventing repeated internal redirects. no-cache permits storage in a cache but requires revalidation before reuse; it does not prohibit caching entirely.
/assets/ and /static/ are common asset directories. Add independent rules for any other directories your build uses, or a missing JS file may still enter the page fallback. A site-wide error_page 404 /index.html can hide missing files, broken APIs and real routing errors.
try_files checks files using the applicable mapping; the final URI is the fallback. root appends the URI to the directory, as described in the Nginx directive reference. For example, /assets/app.js under root /srv/www/app/dist maps to /srv/www/app/dist/assets/app.js.
alias replaces the matched location prefix and uses different path semantics. Do not switch root and alias casually to remove a 404. Check the error log for the file Nginx attempted to open. Permission denied indicates a read-permission problem; another fallback will not fix it.
For “Expected a JavaScript module … MIME type text/html” or Unexpected token '<', open the failed request's Response. If it starts with <!doctype html>, it is usually the homepage or an HTML error document.
After confirming the path, file and status, check that the http context loads the correct mime.types for the installation. Do not force the entire site's default type to JavaScript; HTML, CSS and other files would then receive the wrong type.
After a release, stale HTML may reference old hashed assets that have already been removed. Switch deployment output as a complete version, retain old assets for an appropriate period, and inspect browser, Service Worker and CDN caches. Changing response headers cannot recreate a missing file.
If a CDN fronts the site, compare origin and edge status, Content-Type and response body first. Purge the affected URLs when the origin is correct but the edge remains stale. Do not assume every 404 is a CDN problem, or disable certificate verification to hide an HTTPS configuration error.
For an address such as https://example.com/app/, changing the Nginx location to /app/ alone is insufficient. Vite's asset base, the router's base path, server directory layout and entry fallback must all match that prefix.
A page at /app/ that requests /assets/app.js may send the server looking in the main site's root. Set the base path according to the build tool and router documentation, rebuild, and inspect asset URLs in the generated HTML. The root-deployment example above is not directly suitable for a subdirectory.
An unknown SPA page can still receive HTTP 200 from the server. The frontend should display its own not-found page. If search engines need an accurate HTTP 404, use a solution that can determine route existence on the server rather than treating every URL as valid.
Back up the existing configuration, validate syntax and then reload. If validation fails, retain the working configuration; see Nginx configuration and reload troubleshooting.
sudo nginx -t && sudo systemctl reload nginx
curl -i https://app.example.com/dashboard
curl -i https://app.example.com/assets/not-a-real-file.js
curl -i https://app.example.com/api/not-a-real-endpoint
Expect deep page URLs to receive the entry HTML and missing JS files to return 404. A real API should return JSON, an authentication error or its own 404 according to backend rules, never the frontend homepage. Refresh a deep page in the browser too, checking script execution, login and data loading.
The original article records 10 isolated checks with an existing Nginx 1.19.6 loopback service: deep-page 200 responses, correct JS/CSS types, missing-asset and placeholder-API 404s, and a 404 rather than a redirect loop when the entry file was removed. That local version is not a production installation recommendation. The checks do not cover real frontend execution, TLS, CDNs, Service Workers or application login.