nginx refuses proxy_pass with a path inside a regex location
"proxy_pass" cannot have URI part in location given by regular expressionShort answer
In a regex location, nginx cannot tell which part of the request URI to replace, so proxy_pass must have no URI part. Remove the path after the host and port. If the upstream needs a different path, rewrite the URI with rewrite and break, and let proxy_pass send the rewritten URI as it is.
Fix it fast
1Find out which cause you have
Test the configuration. The message names the file and line with the bad proxy_pass.
sudo nginx -t2Match what you see, then jump to its fix
- 1
The error line points at a proxy_pass whose location starts with ~ or ~*proxy_pass has a path while the location uses ~ or ~*Fix - 2
The upstream expects /v1/... but the client calls /api/...You wanted to change the path, which only works with a prefix locationFix - 3
The location line starts with @, for example location @fallbackThe proxy_pass sits in a named locationFix
- 1
What does the error look like?
"proxy_pass" cannot have URI part in location given by regular expressionnginx: configuration file /etc/nginx/nginx.conf test failed
Cause 1 of 3
proxy_pass has a path while the location uses ~ or ~*
1Check
A URI is the path written after the host and port in proxy_pass. With a regex location the replaced part cannot be determined, so the documentation says proxy_pass should be given without a URI.
grep -n -B2 "proxy_pass" /etc/nginx/conf.d/*.conf2Fix
Delete everything after the host and port. The request URI then goes to the upstream as the client sent it.
location ~ ^/api/ {
proxy_pass http://127.0.0.1:3000;
}3Verify
Test, reload, and request a route through nginx.
sudo nginx -t && sudo systemctl reload nginx
curl -i http://example.com/api/healthConfirmed by nginx.org
Cause 2 of 3
You wanted to change the path, which only works with a prefix location
1Check
With a prefix location, a URI on proxy_pass replaces the matched prefix. A regex location has no such prefix, so that shortcut is not available.
grep -n "location" /etc/nginx/conf.d/*.conf2Fix
Either turn the regex into a prefix location and keep the URI on proxy_pass, or keep the regex, rewrite the path, and send it unchanged.
# prefix form: /api/page becomes /v1/page
location /api/ {
proxy_pass http://127.0.0.1:3000/v1/;
}
# regex form
location ~ ^/api/(.*)$ {
rewrite ^/api/(.*)$ /v1/$1 break;
proxy_pass http://127.0.0.1:3000;
}3Verify
Check what the upstream receives, for example in its access log.
curl -i http://example.com/api/healthConfirmed by nginx.org
Cause 3 of 3
The proxy_pass sits in a named location
1Check
The same rule applies inside named locations, where nginx also cannot replace a matched prefix.
grep -n "location @" /etc/nginx/conf.d/*.conf2Fix
Remove the URI from proxy_pass in the named location.
location @fallback {
proxy_pass http://127.0.0.1:3000;
}3Verify
Test the configuration.
sudo nginx -tConfirmed by nginx.org
How do I stop it coming back?
- Write a trailing slash on proxy_pass only in prefix locations, and treat it as a path, not decoration.
- Run nginx -t in CI or before every reload.
- Prefer prefix locations for plain path mapping; use regex only when you need pattern matching.
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
Servers
Angular routes return 404 from nginx when you refresh or open a link
The home page loads, but refreshing /some/route shows an nginx 404
Angular routes like /users/42 are not files, so nginx looks for them on disk and returns 404.
3 causes, each with a fixServers
Argo CD behind an nginx Ingress loops with too many redirects
307 Temporary Redirect on every request to the Argo CD host
The browser and Argo CD disagree about who handles TLS.
3 causes, each with a fixServers
A Let's Encrypt certificate did not renew with Certbot
Type: connection ... Timeout during connect (likely firewall problem)
Run sudo certbot renew --dry-run and read the Type and Detail lines.
6 causes, each with a fixServers
curl cannot connect to port 80 or 443 on a server running nginx
CURLE_COULDNT_CONNECT (7): Failed to connect() to host or proxy
Exit code 7 means the TCP connection itself failed, before any HTTP happened.
3 causes, each with a fixServers
Django returns a 500 behind Gunicorn and the traceback is nowhere
The traceback shows locally with runserver but not under Gunicorn
With DEBUG set to False, Django's default logging does not print errors to the console.
2 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 fix