Skip to main content

The dbt debug Command

After you install dbt Core and write your profiles.yml file, you need to verify that your laptop can actually talk to your Snowflake data warehouse.

You should never try to run a model (dbt run) without first verifying your connection. If your connection is broken, dbt run will throw a massive wall of confusing error text.

Instead, the very first command you should ever type in a new dbt project is dbt debug.

Topics Covered​

  • What does dbt debug do?
  • Interpreting the Output
  • Common Errors

1. What does dbt debug do?​

The dbt debug command is a diagnostic tool. It performs a sequence of system checks to ensure your environment is configured perfectly.

  1. Configuration Check: It verifies that you have a valid dbt_project.yml file in your current directory.
  2. Profile Check: It verifies that it can find a profiles.yml file (usually at ~/.dbt/profiles.yml), and that the profile name inside it matches the profile name in your project file.
  3. Connection Check: It attempts to establish a physical connection to Snowflake using the credentials provided in the profiles.yml file. It then runs a simple SELECT 1 query to verify network access and permissions.

2. Running the Command​

Open your terminal, ensure you are inside your dbt project folder (e.g., beems_retail), and type:

dbt debug

A Successful Output​

If everything is configured correctly, you will see a series of green "OK" messages, ending with:

==============================
Configuration:
profiles.yml file [OK found and valid]
dbt_project.yml file [OK found and valid]

Required dependencies:
- git [OK found]

Connection:
account: abc1234.ap-south-1.aws
user: ARJUN_DEV
database: BEEMS_DEV
schema: DEV_ARJUN
warehouse: COMPUTE_WH
Connection test: [OK connection ok]

All checks passed!

If you see "All checks passed!", you are ready to start building models.

3. Common Errors​

If something goes wrong, dbt debug is very good at telling you exactly where the problem is.

Error 1: Profile Not Found​

ERROR: Could not find profile named 'beems_retail'

The Fix: You either forgot to create your profiles.yml file in the ~/.dbt/ hidden folder, or the profile name inside that file doesn't exactly match the profile: key in your dbt_project.yml file.

Error 2: Incorrect Password / Account​

Connection test: [ERROR]
Database Error
Incorrect username or password was specified.

The Fix: Double-check your profiles.yml. Ensure your account URL is correct (e.g., you didn't include https:// or .snowflakecomputing.com if you aren't supposed to). Ensure your username is correct, and verify your password.

Error 3: Cannot find dbt_project.yml​

ERROR: dbt found no project configuration file (dbt_project.yml).

The Fix: You are probably in the wrong directory in your terminal! You must cd into your dbt project folder before running any dbt commands.

Summary​

  • Always run dbt debug immediately after setting up your dbt project.
  • It verifies your .yml files are formatted correctly.
  • It runs a simple connection test to ensure your Snowflake credentials (Account, User, Password, Role) are valid.
  • Do not run dbt run or dbt seed until dbt debug says "All checks passed!".