I need help understanding trailing slash behaviour in Nginx

Question

I’m setting up nginx as a reverse proxy for squaremap (a world map viewer for Minecraft servers) and encountering unexpected behavior with trailing slashes. I’ve followed the squaremap documentation for serving with nginx acting as a reverse proxy (https://github.com/jpenilla/squaremap/wiki/Internal-vs-External-Web-Server), but I’m confused by the results. Here’s what I’ve tried:

squaremap is running at 127.0.0.1:39000

Configuration:

location /squaremap {
   proxy_pass http://127.0.0.1:39000;
}

Result: Accessing https://example.com/squaremap returns a 404 error.

location /squaremap {
    proxy_pass http://127.0.0.1:39000/;
}

Result: https://example.com/squaremap shows a blank page, but https://example.com/squaremap/ works fine.

location /squaremap/ {
    proxy_pass http://127.0.0.1:39000/;
}

Result:

https://example.com/squaremap redirects to https://example.com/squaremap/ and then displays the web interface. https://example.com/squaremap/ works as expected.

In my attempt to figure out what was happening, I read part of the nginx documentation on proxy_pass. However, I’m not sure if my interpretation is correct. My understanding is:

If there’s no URI in the proxy_pass directive, the request URI is passed to the upstream unchanged.
If there is a URI in the proxy_pass directive, the part of the request matching the location directive is substituted by the value of the URI in the proxy_pass directive.

Based on this, I created a table of what I think is happening in each of the above cases:

Case	Original Request	Request to Upstream	Result
1	`https://example.com/squaremap`	/squaremap	Error 404
2.a	`https://example.com/squaremap`	/	White page
2.b	`https://example.com/squaremap/`	//	Works
3	`https://example.com/squaremap/`	/	Works

My questions are:

Is my interpretation of how nginx processes these requests correct?
Why do I get different results in cases 2a and 3, even though they seem to send the same request to the upstream?
Why doesn’t it work without the trailing slash, but works with it?
Is there a configuration that would allow both /squaremap and /squaremap/ to work correctly without a redirect?

I’d appreciate any insights into understanding this behavior and how to properly configure nginx for this use case.

Bobby Iliev · Answer

Hey there!

You’re pretty much spot-on with your understanding. Here’s a quick recap:

No trailing slash in proxy_pass: nginx passes the URI as-is to the upstream. So if you hit https://example.com/squaremap, it sends /squaremap to your upstream at 127.0.0.1:39000.
Trailing slash in proxy_pass: nginx swaps out the matching part of the URI with whatever comes after the slash. So with proxy_pass http://127.0.0.1:39000/;, the request to /squaremap/ becomes / on the upstream.

Regarding the difference between 2a and 3:

Case 2a (location /squaremap { proxy_pass http://127.0.0.1:39000/; }):
- When you hit https://example.com/squaremap, nginx sends / to the upstream. That’s why you’re seeing a blank page—it’s probably not the URI that squaremap expects.
Case 3 (location /squaremap/ { proxy_pass http://127.0.0.1:39000/; }):
- nginx knows to redirect /squaremap to /squaremap/, so everything lines up nicely and it works as expected. The trailing slash in the location block ensures that the request is forwarded correctly as / to the upstream.

The trailing slash makes a big difference in how nginx handles the request:

Without it: nginx might send the wrong URI to the upstream, causing issues like the 404 or blank page you saw.
With it: It forwards the request in a way that squaremap expects, which is why it works when you use /squaremap/.

To get both /squaremap and /squaremap/ working smoothly, you can try this setup:

location /squaremap {
    proxy_pass http://127.0.0.1:39000/;
    try_files $uri $uri/ =404;
}

location /squaremap/ {
    proxy_pass http://127.0.0.1:39000/;
}

This way, whether someone hits /squaremap or /squaremap/, nginx will handle it and forward the right request to your upstream server.

Bonus: If you’re cool with always redirecting /squaremap to /squaremap/, you can use:

location /squaremap {
    return 301 /squaremap/;
}

location /squaremap/ {
    proxy_pass http://127.0.0.1:39000/;
}

This approach makes sure that all your traffic goes to /squaremap/ cleanly.

Hope this helps! Let me know how it goes!

- Bobby

Report this

I need help understanding trailing slash behaviour in Nginx

Become a contributor for community

DigitalOcean Documentation

Resources for startups and SMBs

Get our newsletter

The developer cloud

Get started for free