The warning "Your reverse proxy setup is broken" means Jenkins detected that the proxy in front of it is not forwarding requests or rewriting responses correctly. It matters for security as well as function, because a mismatch can cause stale pages, ignored form changes and failing crumb checks.
What a reverse proxy does for Jenkins
A reverse proxy receives inbound HTTP requests, forwards them to Jenkins and returns Jenkins' responses to the original requester. It can provide SSL encryption and offload work such as static files. The Jenkins docs provide examples for Apache, Nginx, Caddy, Lighttpd, HAProxy, Pomerium, Squid, IIS and iptables.
What goes wrong
The setup must rewrite both directions. The two failure families are:
| Problem | Symptom |
|---|---|
| Request rewriting is wrong | Jenkins pages may not display at all |
| Response handling is wrong | Jenkins shows outdated information or ignores changes submitted through its pages |
Jenkins monitors the proxy configuration and shows the warning when it detects a problem. The project has a troubleshooting page for this warning and for unexpected page behavior.
Links to security settings
- CSRF crumbs. Before Jenkins 2.543 the client IP could be part of the crumb, and changing apparent IPs behind a proxy could cause errors. Version 2.543 removed that option, since the session ID gives stronger protection.
- CLI. WebSocket avoids many proxy problems. The HTTP transport may not work reliably, and the proxy must not buffer request or response bodies. SSH behind a proxy needs a host name system property.
- Inbound agents. Since 2.217, agents can use WebSocket and need no extra TCP port, which is simpler through a proxy than a random or fixed TCP port.
A fix checklist
- Read the exact text of the warning in the Manage Jenkins page.
- Compare your proxy config to the Jenkins example for your proxy product.
- Confirm the Jenkins URL in system settings matches the public address, including scheme.
- Verify the proxy forwards the headers Jenkins needs and does not buffer streaming bodies.
- Terminate TLS at the proxy with a current protocol, and keep the Jenkins port closed to the outside.
- Test a form change, a build trigger and an agent connection, then reload the page.
- Keep the proxy config in version control.
Note the Jenkins docs also describe handling access control in Apache instead of Jenkins. That can add a layer, but it does not replace Jenkins authorization.
Try it yourself
The demo shows a DAST web app scan, which can surface header and transport issues on a public Jenkins URL.
Click through it at your own pace, or open it full screen.
Where Safeguard fits
Safeguard enforces policies and gates on changes. Try the free scan.
Quick check
Is the warning only cosmetic?
No. A broken setup can show stale data or ignore submitted changes, and it can interact with crumb and CLI behavior.
Does the docs page give HTTPS steps?
It notes the proxy can handle SSL but points to server specific guides for the steps.
Sources
- Jenkins: Reverse proxy configuration
- Jenkins: CSRF protection
- Jenkins: Jenkins CLI
- Jenkins: Managing security
Last reviewed: 19 October 2026.
