Vault "connection refused" / "no such host" (VAULT_ADDR) in CI

By Kaveh Alemi·Latchkey

The Vault client could not open a connection to the address it was given. "connection refused" means nothing is listening there; "no such host" means DNS could not resolve VAULT_ADDR at all.

What this error means

Commands fail with "Get \"https://vault.example.com/v1/...\": dial tcp: connection refused" or "no such host", or the client defaults to 127.0.0.1:8200 because VAULT_ADDR is empty.

Error making API request.

URL: GET https://127.0.0.1:8200/v1/secret/data/ci/app
Code: -1. Errors:

* Get "https://127.0.0.1:8200/v1/secret/data/ci/app": dial tcp 127.0.0.1:8200: connect: connection refused

Common causes

VAULT_ADDR is unset and defaults to localhost

With no VAULT_ADDR, the client targets https://127.0.0.1:8200, where nothing runs on the hosted runner, so the connection is refused.

The runner cannot reach the Vault host

A private Vault behind a firewall or VPN is unresolvable ("no such host") or unroutable ("connection refused") from a public GitHub-hosted runner.

How to fix it

Set VAULT_ADDR to the reachable endpoint

1. Export VAULT_ADDR from a secret so every step points at the right host.
2. Confirm the runner network can reach it (public endpoint or self-hosted runner in-network).
3. Re-run and verify with vault status.

env:
  VAULT_ADDR: ${{ secrets.VAULT_ADDR }}   # e.g. https://vault.example.com:8200

Use a runner with network access to private Vault

If Vault is private, run the job on a self-hosted runner inside the network rather than a public runner.

jobs:
  deploy:
    runs-on: [self-hosted, vault-network]

How to prevent it

• Always set VAULT_ADDR explicitly; never rely on the localhost default in CI.
• Place jobs that need private Vault on in-network self-hosted runners.
• Add a vault status smoke check early so a bad address fails fast.

Frequently asked questions

Related guides

References

• GitHub Actions documentation