How should I document a failure if the root cause isn't immediately found?

The skill provides a standardized 'findings document' template to record what was checked, hypotheses tested, and suggested next steps so progress isn't lost.

Can this skill be used for local dbt development errors?

No, this skill is specifically optimized for dbt Cloud and platform job failures. For local development issues, you should use the 'using-dbt-for-analytics-engineering' skill instead.

How does this skill assist with data test failures?

It helps you compile the specific test SQL and uses data discovery techniques to query the warehouse, allowing you to see exactly which rows are causing the failure.

What happens if I don't have access to the dbt MCP Admin API?

The skill provides a manual workflow, guiding you to retrieve job logs and run_results.json artifacts via specific URL patterns to ensure investigation can continue.

What is the 'Iron Rule' mentioned in the workflow?

The Iron Rule states you should never modify a test just to make it pass without first understanding the root cause of the failure, preventing bugs from being hidden.

dbt Cloud Error Troubleshooting

Name: dbt Cloud Error Troubleshooting
Author: dbt-labs

bydbt-labs

•

Analytics & Monitoring

Diagnoses and resolves failures in dbt Cloud and platform jobs using systematic workflows and root cause analysis.

This skill provides a systematic framework for identifying and resolving failures within dbt Cloud and platform environments. It streamlines the investigation process by leveraging MCP tools, Git history, and data discovery techniques to classify errors as infrastructure-related, code-based, or data-specific. By enforcing a rigorous approach to root cause analysis and the 'Iron Rule'—never modifying a test without understanding why it failed—this skill helps analytics engineers maintain reliable data pipelines and professional documentation standards during critical job failures.

Key Features

01Standardized templates for documenting findings and investigation progress

02Deep Git integration to trace regressions and identify recent code changes

0313 GitHub stars

04Systematic classification of failures into Infrastructure, Code, or Data categories

05Automated retrieval of dbt Cloud job history and error logs via MCP Admin API

06Step-by-step workflows for compiling test SQL and querying underlying data

Use Cases

01Conducting root cause analysis for production failures occurring immediately after a code merge

02Diagnosing intermittent dbt Cloud job failures with unclear or generic error messages

03Investigating failing data tests to determine if the cause is a logic bug or source data anomaly

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add dbt-labs/dbt-agent-skills troubleshooting-dbt-job-errors

For use in Claude.ai and ChatGPT

Download Skill