What is the difference between ProxyPass and ProxyPassReverse, in terms of what actually breaks without each?

The clean split: one handles the request going out, the other handles a specific header coming back.

ProxyPass forwards requests to the back end and returns the response. For ordinary pages that is all you need, and a simple proxy with only this directive works fine.

ProxyPassReverse rewrites the Location header in redirect responses. That header contains an absolute URL, and the back end writes it using its own address, because it has no idea it is behind a proxy.

So the failure is specific and it is invisible until it happens: the back end sends a redirect to its internal address, the proxy passes that through untouched, and the browser dutifully tries to follow it. The visitor's browser is now attempting to reach an internal hostname that either does not resolve for them or is not reachable — and the internal address is now visible in their address bar.

Which is why it usually shows up not on the first page but at the first login, or the first form submission, since those are the operations that redirect.

The reason it catches people out is the timing. You configure the proxy, load the site, everything works, and you move on. The break appears later, in the specific flows that redirect — sign in, form submission, a trailing-slash correction on a directory.

That last one is worth knowing because it is the most common minimal reproduction: request a directory without a trailing slash and most servers respond with a redirect adding the slash. Without the reverse directive, that redirect points at the internal name.

So the quickest way to test whether you need it is to request a directory path without the slash and watch where the browser goes.

There are two related headers with the same problem and it is worth handling all three at once when you set this up.

• Location, which the reverse directive covers.
• Cookie domain and path, which a companion directive rewrites. Without it, cookies set by the back end can be scoped to the internal hostname and the browser will not send them back, which produces logins that appear to succeed and then immediately forget you.
• Absolute URLs inside the page body, which nothing in this family rewrites. If the application generates links containing its own hostname, the proxy cannot fix that — the application has to be configured with its public address.

That third one is the reason well-behaved applications have a setting for their external base URL, and configuring it is usually cleaner than any amount of rewriting at the proxy.

Worth passing the standard forwarding headers to the back end while you are in there — the original host, the original protocol and the client address.

Otherwise the application logs every request as coming from the proxy, generates links as if it were serving plain HTTP, and any rate limiting it does is applied to one address for all visitors.

Those three headers are the difference between an application that knows it is behind a proxy and one that is merely reachable through one.