dbt troubleshoot

Data Community

Skill notes

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

Iron Rules

Never modify a test to make it pass without understanding why it's failing. 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".

Step 1: Health Check

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

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Data
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@AltimateAI · no license declared
Token usage
Lean
Setup complexity
Guided setup
External API key
Not required
Operating systems
Unspecified (assume cross-platform)
Runtime requirements
Python
Detected file/system behavior
  • Read-only
  • Write / modify
  • Shell exec
Network behavior
Local-only
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

01
Step 1: Health Check

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`

02
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

03
Step 3: Isolate the Problem

Step 3: Isolate the Problem

04
Step 3b: Offline SQL Analysis

Before hitting the database, analyze the compiled SQL offline: Quick-fix tools — use these when the error type is clear: `altimate_core_fix` is best for compilation errors (wrong names, missing objects). `sql_fix` is best for runtime errors (the database told you what's wrong). Use `altimate_core_correct` for iterative multi-round correction when the first fix doesn't resolve the issue. Common findings:

05
Step 3c: Wrong Data Diagnosis — Deep Data Exploration

When a model builds but produces wrong results, the bug is almost always in the data assumptions, not the SQL syntax. You must explore the actual data to find it. Common wrong-data root causes: Fan-out from joins: If row count is higher than expected, a join key isn't unique — check with `SELECT key, count(*) ... GROUP BY 1 HAVING count(*) > 1` Missing rows from INNER JOIN: If row count is lower than expected, switch to LEFT JOIN and check for NULL join keys

06
Step 4: Check Upstream

Most errors cascade from upstream models: Read the parent models. Build them individually. Query the parent data — don't assume it's correct:

07
Step 5: Fix and Verify

After applying a fix: Always build with `--downstream` to catch cascading impacts. Then verify the fix with data queries — don't just trust the build:

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.