Troubleshooting connections

What to do when BuildCaptain can’t reach Jenkins: HTTPS requirements, proxies and login pages, tokens, permissions, and the missing plugin.

Written by Loris Siegenthaler · Maker of BuildCaptain

3 min read

Updated August 20, 2026

When the connection breaks, BuildCaptain shows an orange banner in the sidebar with the reason, plus Retry and Settings buttons. Errors from the server open a dialog with a plain-language summary — expand "What the server sent" to see the raw response, and use Copy Details when reporting a problem.

"The Jenkins URL is invalid" / HTTP refused

BuildCaptain accepts https:// URLs, plus — from BuildCaptain 26.8.3 on — plain http:// for private network addresses only — IP addresses like 10.x.x.x, 172.16–31.x.x, 192.168.x.x, and localhost. This covers internal Jenkins instances that never leave your LAN or VPN. A plain-HTTP hostname (e.g. http://jenkins.example.com/) is refused by design, because it would expose your API token in transit — if that's your setup, connect via the server's private IP address, or better, put Jenkins behind a TLS-terminating reverse proxy.

If the server answers with something that isn't Jenkins — Cloudflare Access, a VPN portal, a company SSO page — BuildCaptain reports that a proxy or login page may be intercepting the request and shows the response it got. Make sure API requests to your Jenkins host bypass interactive login (e.g. service-token headers on the proxy, or connect via VPN first).

401 — token rejected

The username/token pair is wrong or the token was revoked. Create a fresh API token in Jenkins (your name → Security → API Token) and re-enter it in Settings. Note: use the token, not your account password.

403 — no permission

Your account lacks a permission for that action — reading needs Job/Read; run/stop/rerun need Job/Build and Job/Cancel. The server's message is in the error details.

404 on the graph — plugin missing

If pipelines list fine but the stage view reports a missing endpoint, the Pipeline Graph View plugin isn't installed on Jenkins.

If BuildCaptain reports that the saved API token could not be found, open Settings and re-enter it — the token field is the only thing you need to fill; server and username are remembered.

Still stuck?

The Logs page records every request with its status code (tokens and response bodies are never logged). Copy it and send it to us.