← Explore all skills

DATA ENGINEERING / dbt-labs

Troubleshoot dbt Platform Jobs

Diagnose failed platform runs from scoped run logs, node artifacts and source history.

“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.”

01 / THE REASONING

Why this made the selection.

  • It diagnoses dbt platform job failures from run logs and the Admin API, and it forbids changing a test just to make it pass.
  • Local development errors are out of scope, and a cloned project is read rather than executed.
  • The definition requires job_id scoping, classifies infrastructure/code/data errors and treats log or data content as untrusted evidence.
  • Separate infrastructure, compilation and data-test failures

02 / THE REVIEW RECORD

What we actually inspected.

Source review has boundaries.
A clear record is more useful than a “safe” badge.

Material inspected

  • skills/dbt/skills/troubleshooting-dbt-job-errors/SKILL.md
  • README.md
  • LICENSE

Our findings

  • The iron rule is never to modify a test so that it passes without understanding the failure.
  • When the dbt MCP Admin API is absent, the skill asks for job URL, run id, and logs rather than calling the API.
  • A cloned repository is not executed; only files are read.
  • The skill does not cover local development errors and does not guess when the root cause is missing.
  • The definition requires job_id scoping, classifies infrastructure/code/data errors and treats log or data content as untrusted evidence.

Not established by this review

  • The resource was not executed and its tools were not called.
  • No skill execution, authenticated service operation, or outcome benchmark was performed.
  • Not executed: it was not installed or run.

The review applies to the material and revision named here. A newer upstream release can change its behavior.

03 / PUT IT TO WORK

Add a skill to your workflow.

Upstream setup instructions ↗

DOCUMENTED COMMAND

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

Run in your terminal to choose your AI tools, project or global scope, and installation method. This short command follows the current upstream version; the review covers the revision shown above.

Optional: install the reviewed revision

Keeps the original source and installer version where recorded, while leaving your AI tools and installation scope for you to choose.

npx skills add https://github.com/dbt-labs/dbt-agent-skills/tree/7c7b5fa39e61694f1ae2b8ea1b8065e195c814ce/skills/dbt/skills/troubleshooting-dbt-job-errors
  1. Install the pinned skill directory interactively, retaining its bundled references and scripts.
  2. Identify account/project/environment/job/run and retrieve debug logs plus run_results.json or use provided artifacts.
  3. Trace failing nodes and recent changes; verify business validity before changing accepted values or tests.

Before you start

  • A compatible dbt project and the selected CLI/MCP capabilities
  • Warehouse or platform credentials only for operations that require them

04 / FOLLOW THE EVIDENCE

The source trail.

Our notes are separate from the original resource.
Check upstream before adopting a new version.

  1. Pinned skill definition ↗Checked

    https://github.com/dbt-labs/dbt-agent-skills/blob/7c7b5fa39e61694f1ae2b8ea1b8065e195c814ce/skills/dbt/skills/troubleshooting-dbt-job-errors/SKILL.md

    Supports: summary, whySelected, bestFor, limitations, install, access, review

  2. https://github.com/dbt-labs/dbt-agent-skills/blob/7c7b5fa39e61694f1ae2b8ea1b8065e195c814ce/README.md

    Supports: install

  3. Apache-2.0 licence ↗Checked

    https://github.com/dbt-labs/dbt-agent-skills/blob/7c7b5fa39e61694f1ae2b8ea1b8065e195c814ce/LICENSE

    Supports: license

  4. https://raw.githubusercontent.com/dbt-labs/dbt-agent-skills/7c7b5fa39e61694f1ae2b8ea1b8065e195c814ce/skills/dbt/skills/troubleshooting-dbt-job-errors/SKILL.md

    Supports: upstreamDescription, review.notTested, review.reviewedAt

Evidence & Ask