Debugging Errors in dbt: A Survival Guide

print("here")

Have you ever encountered a mysterious error while working on a dbt project and couldn't figure out its source? I've been there too.

Some errors are easy to fix — usually caused by that one tiny change you just made. But others? Sometimes you may face puzzling issues that seem to originate from somewhere outside of your modifications (though I suspect they rarely do 😉).

Let’s break down how to solve them before they drive you crazy.

Types of errors in dbt (and how to outsmart them)

First of all, there are basically only four four types of errors in dbt. Let's explore them.

🚀 Runtime Errors – The "Something is Off" Error

When does it happen? When your project setup is incorrect.

🔧 Fix it by:

• Running dbt debug to check for general issues with the project, like missing profiles or broken database connection.

• Ensuring you're inside the correct dbt project folder (this is where your dbt_project.yml file is).

• Checking your profiles.yml file for the correct profile name.

• Verifying database permissions.

Usually you encounter these when you're setting up the project for the first time. But once everything is connected, you likely won't see these anymore.

---

🔄 Database Errors – When SQL Says ‘Nope’

When does it happen? When dbt tries to execute SQL that the database doesn’t like.

🔧 How to fix it:

• Try to compile the model with dbt compile command and execute the result in database directly. The command will output the compiled code directly to your terminal!

• Alternatively, look inside the /target folder for compiled SQL and test it in your database.

• Run your commands with the --debug flag for extra details (more on that later in the post).

In my opinion, these errors happen most often. Luckily, they are also the easiest to fix, since they are originating from SQL code you write.

---

⚠️ Compilation Errors – Jinja and YAML Gotchas

When does it happen? When dbt struggles to parse your Jinja or YAML code

🔧 Fix it by:

• Checking for invalid Jinja syntax. Maybe you forgot to close a curly bracket or made a type in macro name.

• Ensuring referenced models actually exist.

• Validating that your YAML files are correctly formatted. YAML syntax is also sensitive to margins.

Happens from time to time, but usually dbt can tell you exactly where the issue is.

---

🔗 Dependency Errors – The ‘Circular Nightmare’

When does it happen? When your models reference each other in a loop or have broken dependencies.

🔧 How to fix it:

• Hunt for circular dependencies and break the loop. If the loop seems unbreakable, maybe you could introduce an intermediate model to get out.

• If a model needs to reference itself, use the {{ this }} macro, not the ref()

Easiest problem to understand, but sometimes the hardest to resolve.

---

Debugging like a pro

1️⃣ Use the --debug Flag

dbt hides a lot of details in normal runs, but adding --debug unlocks more insights:

dbt --debug run

Now you can see exactly what dbt is doing behind the scenes. This also works for test and build commands.

2️⃣ Debugging Macros

Macros can feel like a black box, but here’s how to crack them open:

• Compile the macro separately to see what SQL it generates:

dbt compile --inline "{{ macro_name(params) }}"

• Use log() statements to print out variables and debug step by step:

{{ log("Reached here", info=true) }}
{{ log(variable_name, info=true) }}

• Use the built-in Jinja debug() macro like a breakpoint. This will open an interactive iPython debugger where you can inspect variables.

{% my_macro() %} 

... your macro code
{{ debug() }}

{% endmacro %}

---

The Future of Debugging in dbt

With dbt’s recent acquisition of SDF Labs, a new SQL parser is on the way. This means syntax errors could be caught before even running queries — exciting times ahead! But until that feature arrives, these debugging techniques should keep you sane.

What’s the weirdest dbt error you’ve encountered? Let me know about your horror stories in the comments! 👻