skilld
All skills
dbt-labs avatar

/troubleshooting-dbt-job-errors

@540d7d5 official
by dbt Labsdbt-labs/dbt-agent-skills729 stars
62

Diagnoses dbt Cloud/platform job failures by analyzing run logs, querying the Admin API, reviewing git history, and investigating data issues. Use when a dbt Cloud/platform job fails and you need to diagnose the root cause, especially when error messages are unclear or when intermittent failures occur. Do not use for local dbt development errors.

Ask your Agent

Use this Skill: https://skilld.dev/gh/dbt-labs/dbt-agent-skills/troubleshooting-dbt-job-errors

This session only. Nothing lands on disk.

referencesinvestigation-template.md

≈228 tokens on demand. Your agent reads this file only when SKILL.md points to it.

Create docs/investigations/job-failure-<date>.md:

# Job Failure Investigation: <Job Name>

**Date:** YYYY-MM-DD
**Job ID:** <id>
**Status:** Unresolved

## Summary
Brief description of the failure and symptoms.

## What Was Checked

### Tools Used
- [ ] list_jobs_runs - findings
- [ ] get_job_run_error - findings
- [ ] git history - findings
- [ ] Data investigation - findings

### Hypotheses Tested
| Hypothesis | Evidence | Result |
|------------|----------|--------|
| Recent code change | No changes to affected models in 7 days | Ruled out |

## Patterns Observed
- Failures occur between 2-4 AM (peak load time?)
- Always fails on model X

## Suggested Next Steps
1. [ ] Check the data ingestion process to see if new data was added
2. [ ] Check if a new version of dbt or of the dbt adapter was released

## Related Resources
- Link to job run logs
- Link to relevant documentation

Source: SKILL.md on GitHub

Third-party checks

1 warning17d5 checks · Risk SAFE
  • Gen Agent Trust Hub17d

    The troubleshooting-dbt-job-errors skill, authored by dbt-labs, provides a systematic workflow for diagnosing dbt Cloud job failures. It correctly implements security guardrails for handling untrusted logs and repository data, including explicit warnings against executing code from external repositories. The use of diagnostic tools like git and the dbt CLI is appropriate and safe for the stated purpose.

  • Socket17d

    No alerts

  • Snyk17d

    Risk: MEDIUM · 1 issue

  • Runlayer6mo

    1/2 files flagged

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at 540d7d5. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 2 days ago.

Activeupdated 3 weeks ago

Capability

user-invocable
false
metadata
{
  "author": "dbt-labs"
}

Topics

  • Testing
  • dbt
  • dbt-cloud
  • troubleshooting
  • job-failures
  • data-pipeline
  • diagnostics
  • admin-api

README badge

README badge for dbt-labs/dbt-agent-skills/troubleshooting-dbt-job-errors

What it does

Diagnoses dbt Cloud job failures by analyzing run logs, querying the Admin API, reviewing git history, and investigating underlying data. Targets intermittent failures and unclear error messages where the root cause is not obvious from the initial error message alone.

Generated from the current SKILL.md.

Frequently asked

Does this skill work with local dbt development?
No. This skill is specifically for diagnosing dbt Cloud and dbt platform job failures. Use the `using-dbt-for-analytics-engineering` skill for local development errors.
What if I don't have access to the dbt MCP Admin API?
You can still diagnose the failure by asking the user to provide job run logs from dbt Cloud and the run_results.json artifact file. The skill includes instructions for generating the artifact URL.
Should I modify a test to make it pass if I don't know why it's failing?
No. The skill's iron rule is never to modify a test without understanding the failure first. A failing test is evidence of a problem; changing it masks the issue. Always investigate the root cause.
What types of errors does this skill cover?
Three main categories: infrastructure errors (connection timeouts, warehouse issues), code/compilation errors (syntax, undefined macros), and data/test failures (schema mismatches, test assertions). Each has specific investigation steps.

Generated from the current SKILL.md. These answers refresh after source changes.