New: 97,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

dbt Error Debugging

by AltimateAI in AltimateAI/data-engineering-skills

Walks through fixing dbt compilation, database and test errors: read the full error, check upstream models, apply a fix, then verify with dbt build and a data preview.

MITAuto-check passedData & Analytics

Install dbt Error Debugging

skills CLI
$ npx skills add AltimateAI/data-engineering-skills --skill debugging-dbt-errors -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install AltimateAI/data-engineering-skills debugging-dbt-errors --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/AltimateAI/data-engineering-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/dbt/debugging-dbt-errors .claude/skills/debugging-dbt-errors && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
debugging-dbt-errors
GitHub stars
127
Token cost
~1.1k tokens
SKILL.md length
373 words
Files
1
Skills in repo
12
Repo updated
First seen
Licence
MIT

At a glance

Walks through fixing dbt compilation, database and test errors: read the full error, check upstream models, apply a fix, then verify with dbt build and a data preview.

  • Works in 10 steps: Get the Full Error → Inspect Actual Data (For Data Issues) → Read Compiled SQL → …
  • A dbt command fails with a compilation or database error
  • SKILL.md covers Critical Rules, Workflow, Error Categories and Anti-Patterns
  • Calls dbt

What it does

This skill sets a fixed routine for broken dbt models. The agent reads the complete error, inspects actual data with dbt show when output looks wrong, reads the compiled SQL under target/compiled, and sorts the problem into a compilation, database or dependency error. It checks upstream models first, because many failures start there. A table of common fixes covers missing columns, ambiguous columns, type mismatches, division by zero and unbalanced Jinja delimiters.

Every fix must be followed by dbt build rather than compile alone, and a passing build is not treated as proof that the data is right, so the output is previewed again. If a build fails three or more times, the agent stops and rethinks the whole approach. A final step rereads the original request to confirm that column names and calculation logic match what was asked.

When your agent uses it

  • A dbt command fails with a compilation or database error
  • A dbt test fails and you need the cause traced to a model
  • A model builds but produces wrong or unexpected results
  • Troubleshooting why dbt build breaks after an upstream change

Example prompts

  • “dbt build fails on stg_orders with a column not found error. Find the cause and fix it.”
  • “The revenue model runs but the totals look wrong. Inspect the data and trace it upstream.”
  • “My accepted_values test on order_status is failing. Debug it and confirm the fix with a build.”

Requirements

  • A dbt project with dbt installed and a working warehouse connection

Workflow steps

10 steps, taken from the step headings in SKILL.md.

  1. Get the Full Error
  2. Inspect Actual Data (For Data Issues)
  3. Read Compiled SQL
  4. Analyze Error Type
  5. Check Upstream Models
  6. Apply Fix
  7. Rebuild (MANDATORY)
  8. Verify Fix
  9. Re-review Logic Against Requirements
  10. Check Downstream Impact

What it can do on your machine

Read from SKILL.md and the folder at commit 705c68b. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • dbt

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

dbt Error Debugging loads about 1.1k tokens when it runs. Until then it costs about 113 tokens; SKILL.md has 373 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~113
When it runs · the whole SKILL.md, loaded when a task matches
~1.1k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from AltimateAI/data-engineering-skills at commit 705c68b, republished under its MIT licence (© AltimateAI). 373 words, ~1,052 tokens.

Download SKILL.mdSave it as .claude/skills/debugging-dbt-errors/SKILL.md (or your agent's skills folder).
name
debugging-dbt-errors
description
Debugs and fixes dbt errors systematically. Use when working with dbt errors for: (1) Task mentions "fix", "error", "broken", "failing", "debug", "wrong", or "not working" (2) Compilation Error, Database Error, or test failures occur (3) Model produces incorrect output or unexpected results (4) Need to troubleshoot why a dbt command failed Reads full error, checks upstream first, runs dbt build (not just compile) to verify fix.

dbt Troubleshooting

Read the full error. Check upstream first. ALWAYS run dbt build after fixing.

Critical Rules

  1. ALWAYS run dbt build after fixing - compile is NOT enough to verify the fix
  2. If fix fails 3+ times, stop and reassess your entire approach
  3. Verify data after build - build passing doesn't mean output is correct

Workflow

1. Get the Full Error
bash
dbt compile --select <model_name>
# or
dbt build --select <model_name>

Read the COMPLETE error message. Note the file, line number, and specific error.

2. Inspect Actual Data (For Data Issues)

Before fixing "wrong output" or "incorrect results", query the actual data:

bash
# Preview current output
dbt show --select <model_name> --limit 20

# Check specific values with inline query
dbt show --inline "select * from {{ ref('model_name') }} where <condition>" --limit 10

# Compare with expected - look for patterns
dbt show --inline "select column, count(*) from {{ ref('model_name') }} group by 1 order by 2 desc" --limit 10

Understand what's wrong before attempting to fix it.

3. Read Compiled SQL
bash
cat target/compiled/<project>/<path>/<model_name>.sql

See the actual SQL that will run.

4. Analyze Error Type
Error TypeLook For
Compilation ErrorJinja syntax, missing refs, YAML issues
Database ErrorColumn not found, type mismatch, SQL syntax
Dependency ErrorMissing model, circular reference
5. Check Upstream Models
bash
# Find what this model references
grep -E "ref\(|source\(" models/<path>/<model_name>.sql

# Read upstream model to verify columns
cat models/<path>/<upstream_model>.sql

Many errors come from upstream changes, not the current model.

6. Apply Fix

Common fixes:

ErrorFix
Column not foundCheck upstream model's output columns
Ambiguous columnAdd table alias: table.column
Type mismatchAdd explicit CAST()
Division by zeroUse NULLIF(divisor, 0)
Jinja errorCheck matching {{ }} and {% %}
7. Rebuild (MANDATORY)
bash
dbt build --select <model_name>

3-Failure Rule: If build fails 3+ times, STOP. Step back and:

  1. Re-read the original error
  2. Check if your entire approach is wrong
  3. Consider alternative solutions
Show full SKILL.md (148 more words)Show less
8. Verify Fix
bash
# Preview the data
dbt show --select <model_name> --limit 10

# Run tests
dbt test --select <model_name>
9. Re-review Logic Against Requirements

After fixing, re-read the original request and verify:

  • Does the output match what the user asked for?
  • Are the column names exactly as requested?
  • Is the calculation logic correct per the requirements?
  • Did you solve the actual problem, not just make the error go away?
10. Check Downstream Impact
bash
# Find downstream models
grep -r "ref('<model_name>')" models/ --include="*.sql"

# Rebuild downstream
dbt build --select <model_name>+

Error Categories

Compilation Errors
  • Check Jinja syntax: matching {{ }} and {% %}
  • Verify macro arguments
  • Check YAML indentation
Database Errors
  • Read compiled SQL in target/compiled/
  • Check column names against upstream
  • Verify data types
Test Failures
  • Read the test SQL to understand what it checks
  • Compare your model output to expected behavior
  • Check column names, data types, NULL handling

Anti-Patterns

  • Making random changes without understanding the error
  • Assuming the current model is wrong before checking upstream
  • Not reading the FULL error message
  • Declaring "fixed" without running build
  • Getting stuck making small tweaks instead of reassessing

© AltimateAI, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/dbt/debugging-dbt-errors of AltimateAI/data-engineering-skills.

Open the folder on GitHubat commit 705c68b

Compare with similar skills

dbt Error Debugging next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

dbt Error Debugging compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
dbt Error Debugging this skillAltimateAI/data-engineering-skills127—~1.1kAutomated safety check: PassMIT
Analytics Engineerborghei/Claude-Skills874—~3.4kAutomated safety check: PassMIT
Databricks JobsKilo-Org/kilo-marketplace1891 repos~3.1kAutomated safety check: PassCustom licence
Monte Carlo Validation Notebooksickn33/agentic-awesome-skills47k1 repos~1.1kAutomated safety check: PassMIT
Monte Carlo Preventsickn33/agentic-awesome-skills47k1 repos~3.3kAutomated safety check: PassMIT
Data Quality Checksmohitagw15856/pm-claude-skills1.4k—~919Automated safety check: PassMIT

Similar skills

  • Analytics Engineer

    borghei/Claude-Skills

    Analytics engineering across data modeling, dbt, transformation, and semantic layers.

    874 GitHub stars~3.4k tokensUpdated today
    Data & AnalyticsAuto-check passed

  • Databricks Jobs

    Kilo-Org/kilo-marketplace

    Develop and deploy Lakeflow Jobs on Databricks via DABs, Python SDK, or the CLI.

    189 GitHub starsUsed in 1 repo~3.1k tokens
    Data & AnalyticsAuto-check passed

  • Monte Carlo Validation Notebook

    sickn33/agentic-awesome-skills

    Generates SQL validation notebooks for dbt PR changes with before/after comparison queries.

    47k GitHub starsUsed in 1 repo~1.1k tokens
    Data & AnalyticsAuto-check passed

  • Monte Carlo Prevent

    sickn33/agentic-awesome-skills

    Surfaces Monte Carlo data observability context (table health, alerts, lineage, blast radius) before SQL/dbt edits.

    47k GitHub starsUsed in 1 repo~3.3k tokens
    Data & AnalyticsAuto-check passed

  • Data Quality Checks

    mohitagw15856/pm-claude-skills

    Design the data quality checks for a table or pipeline across the standard dimensions.

    1.4k GitHub stars~919 tokensUpdated yesterday
    Data & AnalyticsAuto-check passed

  • Dbt Model Spec

    mohitagw15856/pm-claude-skills

    Spec a dbt model — its grain, sources, transformations, tests, and materialization.

    1.4k GitHub stars~939 tokensUpdated yesterday
    Data & AnalyticsAuto-check passed

More from AltimateAI/data-engineering-skills

All 12 skills in this repo

  • Altimate Data Warehouse Delegate

    AltimateAI/data-engineering-skills

    Delegates dbt and warehouse tasks such as lineage, migrations and cost attribution to the altimate-code CLI agent and relays its answer back.

    127 GitHub stars~1.4k tokensUpdated 5 days ago
    Auto-check passed

  • dbt Model Builder

    AltimateAI/data-engineering-skills

    Creates or modifies dbt models in line with a project's own conventions, then runs dbt build and dbt show to check the output instead of stopping at compile.

    127 GitHub stars~890 tokensUpdated 5 days ago
    Auto-check passed

  • dbt Incremental Models

    AltimateAI/data-engineering-skills

    Helps choose an incremental strategy, design a reliable unique_key and debug failing dbt incremental models, and says when a plain table is the better choice.

    127 GitHub stars~2.3k tokensUpdated 5 days ago
    Auto-check passed

  • dbt Model Documentation

    AltimateAI/data-engineering-skills

    Writes model and column descriptions in dbt schema.yml files, matching the project's existing documentation style and recording grain, business rules and caveats.

    127 GitHub stars~1.2k tokensUpdated 5 days ago
    Auto-check passed

  • Expensive Snowflake Query Finder

    AltimateAI/data-engineering-skills

    Ranks the costliest, slowest or heaviest-scanning Snowflake queries from query history and suggests how to optimize them.

    127 GitHub stars~662 tokensUpdated 5 days ago
    Auto-check passed

  • Migrating SQL To Dbt

    AltimateAI/data-engineering-skills

    Converts legacy SQL to modular dbt models. An agent skill from AltimateAI/data-engineering-skills.

    127 GitHub stars~762 tokensUpdated 5 days ago
    Auto-check passed

Works with

Categories

Questions about dbt Error Debugging

What does dbt Error Debugging do?

Walks through fixing dbt compilation, database and test errors: read the full error, check upstream models, apply a fix, then verify with dbt build and a data preview. This skill sets a fixed routine for broken dbt models. The agent reads the complete error, inspects actual data with dbt show when output looks wrong, reads the compiled SQL under target/compiled, and sorts the problem into a compilation, database or dependency error.

When should I use dbt Error Debugging?

dbt Error Debugging fits situations like: A dbt command fails with a compilation or database error; A dbt test fails and you need the cause traced to a model; A model builds but produces wrong or unexpected results; troubleshooting why dbt build breaks after an upstream change.

How do I install dbt Error Debugging in Claude Code?

Run `npx skills add AltimateAI/data-engineering-skills --skill debugging-dbt-errors -a claude-code`. Or copy the skill folder (skills/dbt/debugging-dbt-errors in AltimateAI/data-engineering-skills) into .claude/skills/debugging-dbt-errors in your project. Claude Code loads it when a task matches its description.

How do I install dbt Error Debugging in Codex?

Run `npx skills add AltimateAI/data-engineering-skills --skill debugging-dbt-errors -a codex`. Or copy the skill folder (skills/dbt/debugging-dbt-errors in AltimateAI/data-engineering-skills) into .agents/skills/debugging-dbt-errors in your project. Codex loads it when a task matches its description.

Can I use dbt Error Debugging in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add AltimateAI/data-engineering-skills --skill debugging-dbt-errors -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/debugging-dbt-errors, .gemini/skills/debugging-dbt-errors, .github/skills/debugging-dbt-errors and .opencode/skills/debugging-dbt-errors in your project.

What does dbt Error Debugging need to run?

Going by SKILL.md and its folder, dbt Error Debugging needs the command-line tools its instructions call (dbt). Our summary lists: A dbt project with dbt installed and a working warehouse connection.

Does dbt Error Debugging access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is dbt Error Debugging safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does dbt Error Debugging use?

dbt Error Debugging is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does dbt Error Debugging use?

About 1.1k tokens (SKILL.md is roughly 4.2k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to dbt Error Debugging?

Skills that share tags, products or a category with dbt Error Debugging: Analytics Engineer (borghei/Claude-Skills, 874 stars), Databricks Jobs (Kilo-Org/kilo-marketplace, 189 stars), Monte Carlo Validation Notebook (sickn33/agentic-awesome-skills, 47k stars) and Monte Carlo Prevent (sickn33/agentic-awesome-skills, 47k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains dbt Error Debugging?

AltimateAI (a GitHub organization) maintains it in AltimateAI/data-engineering-skills, which has 127 GitHub stars. The repository holds 12 skills in this directory. The repository was last updated on October 1, 2026.

Source: AltimateAI/data-engineering-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.