dbt "Database Error ... could not connect to server" in CI

dbt loaded your profile and tried to open a connection to the warehouse, but the network call failed. The "Database Error" wraps the driver message: a refused connection, a bad host, or missing credentials in CI.

What this error means

dbt debug or dbt run stops with "Database Error ... could not connect to server: Connection refused" (Postgres) or an equivalent connection failure, while the same project connects locally.

Database Error
  connection to server at "db.example.com" (10.0.0.5), port 5432 failed:
  Connection refused
    Is the server running on that host and accepting TCP/IP connections?

Common causes

Connection secrets are not injected into the CI step

The warehouse host, user, or password come from environment variables that were never exposed to the job, so dbt sends empty or default values and the connection is refused.

The warehouse is unreachable from the runner

A private database with no public route, an IP allowlist that excludes the runner, or a closed port means the TCP connection never establishes.

How to fix it

Inject warehouse credentials from secrets

1. Store host, user, and password as repository or organization secrets.
2. Map them into the dbt step env so profiles.yml env_var() lookups resolve.
3. Run dbt debug first to confirm the connection before dbt run.

env:
  DBT_HOST: ${{ secrets.DBT_HOST }}
  DBT_USER: ${{ secrets.DBT_USER }}
  DBT_PASSWORD: ${{ secrets.DBT_PASSWORD }}
run: dbt debug

Open a network path to the warehouse

Add the runner IP range to the database allowlist, or run against a CI-reachable database. A persistently refused connection will not be fixed by retrying.

How to prevent it

• Keep all warehouse credentials in CI secrets, never in committed profiles.
• Run dbt debug as the first dbt step so connection problems surface early.
• Allowlist runner egress IPs (or use a CI-reachable warehouse) for private databases.

Related guides