Maaz Zindani

Loading the index…

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

nginx refuses proxy_pass with a path inside a regex location

Error"proxy_pass" cannot have URI part in location given by regular expression

Short 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.

  • Applies to nginx 1.26
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Test the configuration. The message names the file and line with the bad proxy_pass.

    sudo nginx -t
  2. 2Match what you see, then jump to its fix

    1. 1The error line points at a proxy_pass whose location starts with ~ or ~*proxy_pass has a path while the location uses ~ or ~*Fix
    2. 2The upstream expects /v1/... but the client calls /api/...You wanted to change the path, which only works with a prefix locationFix
    3. 3The location line starts with @, for example location @fallbackThe proxy_pass sits in a named locationFix

What does the error look like?

  • "proxy_pass" cannot have URI part in location given by regular expression
  • nginx: 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/*.conf

2Fix

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/health

Confirmed by nginx.org

Did this fix it?

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/*.conf

2Fix

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/health

Confirmed by nginx.org

Did this fix it?

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/*.conf

2Fix

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 -t

Confirmed by nginx.org

Did this fix it?

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

Next step

Want this handled for good?

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