VPS Tutorials
Nginx proxy_pass: keep, strip or replace an API path prefix
A backend that works directly can return 404 through Nginx. Compare three proxy_pass forms, inspect the upstream path, and verify queries, POST requests and redirects.

Your backend works when called directly, but returns 404 through Nginx. Compare the path reaching the application before changing the proxy. A client requests /api/users, while the backend may expect /users or already handle /api/users. One slash in proxy_pass can change which route receives the request.
This guide covers ordinary HTTP prefix locations: keeping, removing and replacing a path prefix. Establish the intended upstream URL first. Adding rewrites, redirects and page fallbacks together makes it difficult to identify where the path changed.
Test the backend's actual routes from the VPS. Replace the example port with its real listening address. Inside a container, 127.0.0.1 may refer to neither the host nor another container.
curl -i 'http://127.0.0.1:3000/users?limit=1'
curl -i 'http://127.0.0.1:3000/api/users?limit=1'
curl -i 'https://app.example.com/api/users?limit=1'
sudo nginx -T
An authenticated endpoint may return 401 or 403 without credentials; that alone does not mean the route is missing. Check the backend access log for the path, method and status, and confirm which server and location match the domain. Remove tokens, cookies and sensitive internal addresses before sharing logs or configuration.
If your existing access log records $status and $upstream_status, compare the client response with the upstream response. An empty upstream status calls for checking local responses, caching and whether the request entered a proxy location. Custom error handling can change the error page, so its appearance is not reliable evidence of the source.
A 502 caused by an unreachable backend needs an address, port or container-network investigation; see troubleshooting 502 and 504. A trailing slash will not normally fix a refused connection.
Assume the request is /api/users?limit=1, the location is /api/, and no additional rewrite applies:
| proxy_pass value | Path received upstream | Intended backend route |
|---|---|---|
http://127.0.0.1:3000 | /api/users?limit=1 | Already includes /api/ |
http://127.0.0.1:3000/ | /users?limit=1 | Starts at /users |
http://127.0.0.1:3000/v1/ | /v1/users?limit=1 | Requires the /v1/ prefix |
The relevant distinction is whether the address includes a URI component; / by itself is a URI too. The Nginx proxy_pass reference explains that an included URI replaces the matched part of the normalized prefix. Without a URI, Nginx preserves the original request URI, subject to separate rules when an internal rewrite changes it.
location /api/ {
proxy_pass http://127.0.0.1:3000;
}
If the backend already defines /api/, leave the trailing / out of this example. Adding it strips the prefix: the backend receives /users, which may not exist.
location /api/ {
proxy_pass http://127.0.0.1:3000/;
}
The matched /api/ becomes /. Test that mapping before adding another rewrite. If the API starts working but documentation or login redirects remain incorrect, check the application's public URL settings next.
location /api/ {
proxy_pass http://127.0.0.1:3000/v1/;
}
A request for /api/users reaches /v1/users. Keep / at both boundaries. Using /v1 instead can concatenate the remaining path into /v1users, a different route.
These are alternative location snippets. Choose the one that matches your backend and merge it into the existing site. Keep certificates, authentication, headers, rate limits and other routes. Do not insert all three into the same server. WebSocket and streaming endpoints also require their own proxy settings; a correct path mapping alone is insufficient.
A prefix location ending in / and handled by a proxy directive can trigger Nginx's automatic 301 for the equivalent path without the slash. With a configuration such as /api/, a request for /api redirects to /api/; see the special handling of locations.
Inspect the first response with curl without -L. Automatically following redirects can hide the cause. For login callbacks and POST endpoints, verify both the final method and destination rather than depending on a client's treatment of 301.
If /api is itself a required endpoint, define an exact match with an explicit upstream route. Do not redirect every request to a slash-suffixed variant. A normal /api/ prefix does not treat /apiary as the same path either.
The simple mappings in the table preserve the example query parameters. For POST, also verify the method, body and Content-Type. A successful GET does not establish that order submission or file uploads work. Review any existing directives that change the proxy method, body or headers.
Mapping an incoming API path does not automatically update URLs generated by the application. Absolute redirects, asset references in HTML, Cookie Path and login callbacks may still assume the original root path. Configure the application's supported external URL or base path before considering response rewriting in the proxy.
An application without subpath support is often easier to maintain on a separate subdomain. A global HTML replacement changing every / into /api/ can also alter assets, APIs and third-party links incorrectly.
Regex and named locations, proxy_pass containing variables, and requests changed by rewrite ... break may follow different rules. If you see $request_uri, capture groups or multiple internal redirects, examine the actual configuration alongside the official definitions.
When several locations exist, check whether a more specific or regex rule takes over. For URL-encoded paths, repeated slashes and signed query parameters, retain the original request and compare it carefully. The ordinary paths above do not prove compatibility with encoding or signatures.
Do not turn an API 404 into the frontend homepage. A 200 response containing HTML still fails for a client expecting API data. For static files or an SPA refresh, use the separate Vue and React refresh-404 guide.
Back up the site configuration, check syntax, then reload:
sudo nginx -t && sudo systemctl reload nginx
curl -i 'https://app.example.com/api/users?limit=1'
Use permitted test requests to verify the upstream path, query parameters, method and body. Then check login redirects and page assets. Avoid testing production with requests that create orders, charge payments or send messages.
The original article records 12 isolated checks with an existing Nginx 1.19.6 installation and a mock backend, covering the three prefix mappings, query parameters, POST content and automatic 301. When the backend accepted only /root-only, preserving the external prefix produced 404 and stripping it produced 200. That local version is not a production installation recommendation. The checks do not cover real application authentication, TLS, CDNs, WebSockets, browser login or rewriting URLs in responses.