Octopus Deploy "Unable to connect to the Octopus Deploy server" in CI
octo could not open a connection to the server URL you passed. The address is missing a scheme or path, points at the wrong host, or the runner has no network route to a self-hosted Octopus behind a firewall or VPN.
What this error means
octo fails early with "Unable to connect to the Octopus Deploy server. Please check the server URL" before any project or release work begins.
Octopus.Client.Exceptions.OctopusException: Unable to connect to the Octopus
Deploy server. Please check the server URL and that Octopus is running.Common causes
The server URL is wrong or incomplete
The --server value is missing https://, has a trailing typo, or points at a stale hostname, so the CLI never reaches a live Octopus API.
The runner cannot route to a self-hosted server
A self-hosted Octopus sits behind a firewall or VPN that the CI runner is not on, so the address resolves but the connection is refused or times out.
How to fix it
Pass the full, reachable server URL
- Confirm the exact base URL from the Octopus web portal, including https:// and any path prefix.
- Store it as OCTOPUS_URL and pass it with --server.
- From the runner, curl the /api endpoint to confirm reachability.
octo create-release --server "https://octopus.example.com" \
--apiKey "$OCTOPUS_API_KEY" --project "Web"Open a network path for self-hosted servers
If Octopus is internal, run the deploy from a self-hosted runner inside the network, or expose the API to the CI network through an allowlisted route.
How to prevent it
- Store the server URL as a single CI secret used by every step.
- Verify reachability with a curl of /api at the start of the job.
- Use self-hosted runners with network access for internal Octopus servers.