Back to tutorials

dbt Debug Command: Usage & Examples


Welcome to this tutorial on the dbt debug command. dbt is a powerful tool used by data professionals to transform data in their warehouses more effectively. Debugging is a crucial part of any data transformation process, and dbt provides a built-in command for this purpose: dbt debug.

Understanding the dbt debug Command

The dbt debug command is a utility function that tests the database connection and displays information for debugging purposes. It checks the validity of your project file and your installation of any requisite dependencies (like git). It’s important to distinguish this from the --debug option, which increases logging verbosity but doesn’t perform the same checks as dbt debug.

Using the dbt debug Command

To use dbt debug, navigate to your dbt project directory and run the command:

dbt debug

This will output information about your dbt installation, your project, and your database connection. If there are any issues with your setup, dbt debug will highlight them.

Example: Finding the Location of the profiles.yml File

The profiles.yml file is where dbt stores database connection information. You can use dbt debug to find its location:

dbt debug --config-dir

This will output the directory where profiles.yml is located. To view the file, you can use the open command:

open /path/to/profiles.yml

Replace /path/to/ with the output from the previous command.

Common Issues and How to Debug Them

Let’s say you’re working on a business analytics project and you’ve set up a dbt project to transform your sales data. You run your transformations, but the output isn’t what you expected. This is where dbt debug comes in.

Run dbt debug and check the output. If there’s an issue with your database connection, dbt debug will tell you. If your project file is invalid, dbt debug will tell you. By using dbt debug, you can quickly identify and fix issues with your dbt setup.


The dbt debug command is a powerful tool for identifying and fixing issues with your dbt setup. By using dbt debug, you can ensure that your data transformations run smoothly and produce the expected results.


dbt DAG
database icon
The first SQL editor with built-in dbt Core ™
Simplified dbt development - Create and manage your dbt models and macros all in one place with PopSQL