dbt-troubleshoot

dbt Troubleshooting

Requirements

Agent: any (read-only diagnosis), builder (if applying fixes) Tools used: bash (runs altimate-dbt commands), read, glob, edit, altimate_core_semantics, altimate_core_column_lineage, altimate_core_correct, altimate_core_fix, sql_fix

When to Use This Skill

Use when:

• A dbt model fails to compile or build
• Tests are failing
• Model produces wrong or unexpected data
• Builds are slow or timing out
• User shares an error message from dbt

Do NOT use for:

• Creating new models → use dbt-develop
• Adding tests → use dbt-test
• Analyzing change impact → use dbt-analyze

Iron Rules

1. Never modify a test to make it pass without understanding why it's failing.
2. Fix ALL errors, not just the reported one. After fixing the specific issue, run a full dbt build. If other models fail — even ones not mentioned in the error report — fix them too. Your job is to leave the project in a fully working state. Never dismiss errors as "pre-existing" or "out of scope".

Diagnostic Workflow

Step 1: Health Check

altimate-dbt doctor
altimate-dbt info

If doctor fails, fix the environment first. Common issues:

• Python not found → reinstall or set --python-path
• dbt-core not installed → pip install dbt-core
• No dbt_project.yml → wrong directory
• Missing packages → if packages.yml exists but dbt_packages/ doesn't, run dbt deps

Step 2: Classify the Error

Error Type	Symptom	Jump To
Compilation Error	Jinja/YAML parse failure	references/compilation-errors.md
Runtime/Database Error	SQL execution failure	references/runtime-errors.md
Test Failure	Tests return failing rows	references/test-failures.md
Wrong Data	Model builds but data is incorrect	Step 3 below

Step 3: Isolate the Problem

# Compile only — catches Jinja errors without hitting the database
altimate-dbt compile --model <name>

# If compile succeeds, try building
altimate-dbt build --model <name>

# Probe the data directly
altimate-dbt execute --query "SELECT count(*) FROM {{ ref('<name>') }}" --limit 1
altimate-dbt execute --query "SELECT * FROM {{ ref('<name>') }}" --limit 5