Features
"dbt debug" is a dbt CLI command that validates your profile, tests database connectivity, and checks required dependencies before a dbt run.
The "dbt debug" command validates credentials, profile targets, and adapter health so teams can resolve issues before running transformations.
dbt debug?"dbt debug" is a built-in dbt CLI command that runs a series of connectivity, configuration, and permission checks against the active profile.It confirms that your warehouse credentials work and that dbt can create, read, and write to the target schema.
dbt debug in Your Workflow?Running "dbt debug" early in local setup or CI pipelines catches misconfigured profiles and expired credentials fast, preventing long debugging sessions after a failed "dbt run" or "dbt test".
dbt debug Work Internally?The command loads the selected profile, instantiates the adapter, and sequentially executes adapter-specific SQL such as current_user, list_schemas, and create_drop table operations to verify permissions.
dbt debug Detect?Typical failures include missing profile.yml keys, unreachable hosts, invalid passwords, insufficient CREATE permissions, or unsupported adapter versions.Each failure surfaces a clear error message and stack trace.
dbt debug Step-by-StepNavigate to your dbt project root and execute:
$ dbt debug --target prod
Add flags like --config-dir or --profile-dir to test alternative profile locations without editing environment variables.
dbt debug ChecksVersion-control your profiles.yml template, use environment variables for secrets, and integrate "dbt debug" in pre-commit hooks or GitHub Actions to guarantee every merge request has a healthy connection.
dbt debug# .github/workflows/dbt.yml
- name: Validate profile
run: dbt debug --target ci
This step fails fast if cloud credentials expire, alerting engineers before downstream jobs consume compute credits.
If the profile uses environment variables that are missing in the shell, export them or add them to your CI secrets manager.
Specifying a non-existent target flag causes dbt to load default settings.Ensure the target name matches a section in profiles.yml.
"dbt debug" may succeed on connectivity but fail on write tests. Grant CREATE and DROP permissions on the target schema or supply a dedicated service role.
dbt debugGalaxy’s desktop SQL editor lets you run "dbt debug" inside an integrated terminal while its AI copilot explains failures and suggests permission fixes, reducing time spent parsing stack traces.
.
Data pipelines fail most often due to environment drift—expired passwords, dropped roles, or renamed targets. "dbt debug" offers a quick, codified smoke test that verifies connectivity before compute-heavy transformations run. Embedding the command in CI saves time, money, and team confidence by ensuring every developer and deployment has a valid data warehouse connection.
Not technically, but running it in automated pipelines ensures failures surface quickly and cheaply.
Use --connection-only (dbt >=1.7) to skip write tests when your role is read-only.
Galaxy can open your dbt project directory, let you execute "dbt debug" in-app, and uses its AI copilot to interpret error messages.
It may create and drop a temporary table to test write permissions but leaves no lasting artifacts.
.avif){kind=logo}
