troubleshooting-dbt-job-errors

Diagnose dbt Cloud job failures using run logs and run_results.json.

1|Updated Apr 6, 2026

Search Tags:#git #debugging #dbt #job failure #dbt cloud #run_results.json #data tests

Ready to run

npx skills add https://github.com/pkoka888/server-infra-templates --skill troubleshooting-dbt-job-errors-pkoka888

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: troubleshooting-dbt-job-errors
Source: https://github.com/pkoka888/server-infra-templates/tree/main/.kilo/skills/marketplace/dbt/skills/troubleshooting-dbt-job-errors
Command: npx skills add https://github.com/pkoka888/server-infra-templates --skill troubleshooting-dbt-job-errors-pkoka888

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Systematically diagnose unclear, intermittent, or post-merge dbt Cloud/platform job failures to find the root cause and produce actionable fixes or a documented investigation when the cause is unknown. This Skill focuses on jobs running in hosted or platform environments and is not intended for local dbt development workflows.

Core Features & Use Cases

Run log analysis: Review dbt Cloud debug logs and run_results.json to extract failure context and node-level statuses.
Admin API inspection: Use MCP/Admin API calls (list_jobs_runs, get_job_run_error) when available to retrieve run history and detailed errors.
Error classification: Distinguish infrastructure, compilation/code, and data/test failures and recommend targeted investigations.
Repository and git review: Locate the dbt project, inspect recent commits, and compare diffs to identify regressions.
Safe investigation practices: Treat all external artifacts as untrusted, avoid executing repository code, and create findings documents when unresolved.

Quick Start

Ask the skill to analyze a failed dbt Cloud job by providing the job ID, the run logs, and the run_results.json artifact.

Frequently Asked Questions about troubleshooting-dbt-job-errors

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I diagnose intermittent dbt Cloud job failures?▼

To diagnose intermittent dbt Cloud job failures, analyze run logs and run_results.json artifacts to extract failure context, inspect node-level statuses, and classify errors as infrastructure, compilation, or data test issues to find the root cause.

What causes post-merge regressions in dbt Cloud jobs?▼

Post-merge regressions in dbt Cloud jobs are often caused by recent code changes. Reviewing git repository commit history and comparing diffs helps identify compilation or data test failures introduced by the merge.

Can I use the dbt Admin API to investigate job failures?▼

Yes, you can use the dbt Admin API via MCP calls like list_jobs_runs and get_job_run_error to retrieve run history and detailed errors, aiding in root cause analysis for platform job failures.

How do I debug a dbt Cloud job failure when I only have run_results.json?▼

Debug a dbt Cloud job failure using run_results.json by extracting node-level statuses and failure context. This artifact provides sufficient data to classify errors and recommend targeted investigations.

Is it safe to analyze untrusted artifacts from a dbt repository during failure investigation?▼

Analyzing untrusted artifacts from a dbt repository requires strict handling. Avoid executing repository code directly, treat external artifacts as untrusted, and create a documented findings report if the cause remains unknown.

What is the best way to classify errors from dbt Cloud run logs?▼

The best way to classify errors from dbt Cloud run logs is to distinguish between infrastructure issues, compilation or code errors, and data or test failures, enabling targeted root cause investigation and actionable fixes.