dbt "database error" on run: connection checklist

TL;DR

Work the connection chain from the inside out: dbt config, then credentials, then network, then the warehouse itself. Run dbt debug first, it checks every link and tells you exactly which one broke. Nine times out of ten the answer is a wrong profile target, an expired credential, or a warehouse that is asleep or unreachable, and the checklist below finds it in minutes.

dbt "database error" on run: connection checklist

Use this when

• every model fails with a database error before any SQL runs
• dbt debug reports a connection failure on one of its checks
• you just changed profiles, credentials, or environments

Not for this skill when

• some models succeed and one fails, that is a model bug not a connection bug
• the error is permission denied on a specific schema, check grants instead
• compilation fails before dbt ever touches the database

Steps

1. Run the built-in connection checker and read which link in the chain failed:

dbt debug

Expected output: a checklist with pass or fail per item, ending in "All checks passed!" when healthy. The first failing line is your culprit, start there.

1. Confirm you are pointing at the profile target you think you are, since the wrong target explains most mysteries:

dbt debug --target dev | head -25

Expected output: the connection details dbt resolved for that target. A surprising host, database, or schema here means profiles.yml is not what you assume it is.

1. Verify the credentials file exists and your project block looks right:

ls -la ~/.dbt/profiles.yml && grep -A6 "my_project:" ~/.dbt/profiles.yml | head -14

Expected output: the file exists and your project's profile block shows the expected target settings. A missing file or a typo in the project name fails everything downstream.

1. Test the network path to the warehouse host from this machine, ruling out dbt entirely:

nc -zv warehouse-host.example.com 5432

Expected output: a succeeded-style message. A timeout here means firewall, VPN, or DNS trouble, not a dbt problem. Replace the host and port with your warehouse's real values.

1. Check the warehouse itself is awake and accepting your role, since asleep warehouses fail the same way as broken credentials:

SELECT current_user, current_database();

Expected output: your dbt user and database echoed back. On Snowflake also verify the warehouse is running and your role has USAGE on it, which is the step everyone forgets.

1. Re-run the full debug after each fix until the whole chain is green, then build one small model:

dbt debug && dbt run --select stg_orders

Expected output: all checks pass and the model builds. Fix one layer at a time and re-verify, since multiple broken layers mask each other.

Variant phrasings

dbt could not connect to database

Start at step 1. dbt debug distinguishes auth failures from network failures, and those need totally different fixes, so do not guess.

dbt debug fails on credentials

Usually an expired password, a rotated key, or an env var that is not exported in this shell. Step 2 prints the resolved target so you can see what dbt actually tried.

dbt works locally but not in CI

CI environments often miss env vars or VPN access that your laptop has. Diff the debug output between the two machines line by line and the gap appears.

Why it happens

dbt has to resolve four things before running any SQL: which profile target, which credentials, a network route to the host, and a live warehouse that accepts the role. A break at any layer surfaces as the same generic "database error", which is why the fix is a checklist walk from the inside out rather than one clever command.

Edge cases

• Env var credentials like {{ env_var('DBT_PASSWORD') }} fail silently when the var is unset in a new shell. Export it or check your shell profile.
• Key-pair auth paths are machine-specific and break when copied between laptops and CI runners.
• Multiple profiles.yml files: dbt reads --profiles-dir or ~/.dbt, and a stray file wins silently. Pass the dir explicitly in CI.
• Idle timeouts: some warehouses kill idle connections, so a long compile phase can die before the first query. It looks like a connection bug but it is a timeout.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_dKJJ9yQAAp6dKfLZZgWJjg