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

When proxy_pass includes a URI (anything after the host and port, even a single /), nginx replaces the part of the request URI that matched the location with that URI. In a regular-expression location nginx cannot know which part matched, so it refuses the configuration: [emerg] "proxy_pass" cannot have URI part in location given by regular expression, or inside named location, or inside "if" statement, or inside "limit_except" block.

Reproduce it

mkdir -p logs temp
cat > nginx.conf <<'EOF'
pid logs/nginx.pid;
events {}
http {
  server {
    listen 127.0.0.1:8080;
    location ~ ^/api/ {
      proxy_pass http://127.0.0.1:3000/v1/;
    }
  }
}
EOF
nginx -p . -c nginx.conf -e stderr -t 2>&1 | sed -E 's/^[0-9/]+ [0-9:]+ \[([a-z]+)\] [0-9#]+: /[\1] /'
exit "${PIPESTATUS[0]}"

[emerg] "proxy_pass" cannot have URI part in location given by regular expression, or inside named location, or inside "if" statement, or inside "limit_except" block in ./nginx.conf:7
nginx: configuration file ./nginx.conf test failed

Fix: rewrite, then proxy without a URI

location ~ ^/api/ {
    rewrite ^/api/(.*)$ /v1/$1 break;   # /api/users -> /v1/users
    proxy_pass http://127.0.0.1:3000;   # no URI part
}

Fix: use a prefix location

If you do not need a regular expression, a prefix location accepts a URI in proxy_pass and replaces the matched prefix:

location /api/ {
    proxy_pass http://127.0.0.1:3000/v1/;   # /api/users -> /v1/users
}

See proxy_pass with and without a trailing slash for how the replacement works.