troubleshooting-dbt-job-errors

Name: troubleshooting-dbt-job-errors
Author: dbt-labs

565installs55forks

How to install troubleshooting-dbt-job-errors?

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

$npx -y skills add dbt-labs/dbt-agent-skills --skill troubleshooting-dbt-job-errors

Installs into the current project.

Summary

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 inter

Files · 1

View on GitHub

SKILL.md

1	# Troubleshooting dbt Job Errors
2
3	Systematically diagnose and resolve dbt Cloud job failures using available MCP tools, CLI commands, and data investigation.
4
5	## When to Use
6
7	- dbt Cloud / dbt platform job failed and you need to find the root cause
8	- Intermittent job failures that are hard to reproduce
9	- Error messages that don't clearly indicate the problem
10	- Post-merge failures where a recent change may have caused the issue
11
12	Not for: Local dbt development errors - use the skill `using-dbt-for-analytics-engineering` instead
13
14	## The Iron Rule
15
16	Never modify a test to make it pass without understanding why it's failing.
17
18	A failing test is evidence of a problem. Changing the test to pass hides the problem. Investigate the root cause first.
19
20	## Rationalizations That Mean STOP
21
22	\| You're Thinking... \| Reality \|
23	\|-------------------\|---------\|
24	\| "Just make the test pass" \| The test is telling you something is wrong. Investigate first. \|
25	\| "There's a board meeting in 2 hours" \| Rushing to a fix without diagnosis creates bigger problems. \|
26	\| "We've already spent 2 days on this" \| Sunk cost doesn't justify skipping proper diagnosis. \|
27	\| "I'll just update the accepted values" \| Are the new values valid business data or bugs? Verify first. \|
28	\| "It's probably just a flaky test" \| "Flaky" means there's an overall issue. Find it. We don't allow flaky tests to stay. \|
29
30	## Workflow
31
32	```mermaid
33	flowchart TD
34	A[Job failure reported] --> B{MCP Admin API available?}
35	B -->\|yes\| C[Use list_jobs_runs to get history]
36	B -->\|no\| D[Ask user for logs and run_results.json]
37	C --> E[Use get_job_run_error for details]
38	D --> F[Classify error type]
39	E --> F
40	F --> G{Error type?}
41	G -->\|Infrastructure\| H[Check warehouse, connections, timeouts]
42	G -->\|Code/Compilation\| I[Check git history for recent changes]
43	G -->\|Data/Test Failure\| J[Use discovering-data skill to investigate]
44	H --> K{Root cause found?}
45	I --> K
46	J --> K
47	K -->\|yes\| L[Create branch, implement fix]
48	K -->\|no\| M[Create findings document]
49	L --> N[Add test - prefer unit test]
50	N --> O[Create PR with explanation]
51	M --> P[Document what was checked and next steps]
52	```
53
54	## Step 1: Gather Job Run Information
55
56	### If dbt MCP Server Admin API Available
57
58	Use these tools first - they provide the most comprehensive data:
59
60	\| Tool \| Purpose \|
61	\|------\|---------\|
62	\| `list_jobs_runs` \| Get recent run history, identify patterns \|
63	\| `get_job_run_error` \| Get detailed error message and context \|
64
65	```
66	# Example: Get recent runs for job 12345
67	list_jobs_runs(job_id=12345, limit=10)
68
69	# Example: Get error details for specific run
70	get_job_run_error(run_id=67890)
71	```
72
73	### Without MCP Admin API
74
75	Ask the user to provide these artifacts:
76
77	1. Job run logs from dbt Cloud UI (Debug logs preferred)
78	2. `run_results.json` - contains execution status for each node
79
80	To get the `run_results.json`, generate the artifact URL for the user:
81	```
82	https://<DBT_ENDPOINT>/api/v2/accounts/<ACCOUNT_ID>/runs/<RUN_ID>/artifacts/run_results.json?step=<STEP_NUMBER>
83	```
84
85	Where:
86	- `<DBT_ENDPOINT>` - The dbt Cloud endpoint. e.g
87	- `cloud.getdbt.com` for the US multi-tenant platform (there are other endpoints for other regions)
88	- `ACCOUNT_PREFIX.us1.dbt.com` for the cell-based platforms (there are different cell endpoints for different regions and cloud providers)
89	- `<ACCOUNT_ID>` - The dbt Cloud account ID
90	- `<RUN_ID>` - The failed job run ID
91	- `<STEP_NUMBER>` - The step that failed (e.g., if step 4 failed, use `?step=4`)
92
93	Example request:
94	> "I don't have access to the dbt MCP server. Could you provide:
95	> 1. The debug logs from dbt Cloud (Job Run → Logs → Download)
96	> 2. The run_results.json - open this URL and copy/paste or upload the contents:
97	> `https://cloud.getdbt.com/api/v2/accounts/12345/runs/67890/artifacts/run_results.json?step=4`
98
99	## Step 2: Classify the Error
100
101	\| Error Type \| Indicators \| Primary Investigation \|
102	\|------------\|-----------\|----------------------\|
103	\| Infrastructure \| Connection timeout, warehouse error, permissions \| Check warehouse status, connection settings \|
104	\| Code/Compilation \| Undefined macro, syntax error, parsing error \| Check git history for recent changes, use LSP tools \|
105	\| Data/Test Failure \| Test failed with N results, schema mismatch \| Use `discovering-data` skill to query actual data \|
106
107	## Step 3: Investigate Root Cause
108
109	### For Infrastructure Errors
110
111	1. Check job configuration (timeout settings, execution steps, etc.)
112	2. Look for concurrent jobs comp

People who liked this also viewed

6 picks

Type

troubleshooting-dbt-job-errors

565installs55forks

View on GitHub

How to install troubleshooting-dbt-job-errors?

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

$npx -y skills add dbt-labs/dbt-agent-skills --skill troubleshooting-dbt-job-errors

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Troubleshooting dbt Job Errors
2
3	Systematically diagnose and resolve dbt Cloud job failures using available MCP tools, CLI commands, and data investigation.
4
5	## When to Use
6
7	- dbt Cloud / dbt platform job failed and you need to find the root cause
8	- Intermittent job failures that are hard to reproduce
9	- Error messages that don't clearly indicate the problem
10	- Post-merge failures where a recent change may have caused the issue
11
12	Not for: Local dbt development errors - use the skill `using-dbt-for-analytics-engineering` instead
13
14	## The Iron Rule
15
16	Never modify a test to make it pass without understanding why it's failing.
17
18	A failing test is evidence of a problem. Changing the test to pass hides the problem. Investigate the root cause first.
19
20	## Rationalizations That Mean STOP
21
22	\| You're Thinking... \| Reality \|
23	\|-------------------\|---------\|
24	\| "Just make the test pass" \| The test is telling you something is wrong. Investigate first. \|
25	\| "There's a board meeting in 2 hours" \| Rushing to a fix without diagnosis creates bigger problems. \|
26	\| "We've already spent 2 days on this" \| Sunk cost doesn't justify skipping proper diagnosis. \|
27	\| "I'll just update the accepted values" \| Are the new values valid business data or bugs? Verify first. \|
28	\| "It's probably just a flaky test" \| "Flaky" means there's an overall issue. Find it. We don't allow flaky tests to stay. \|
29
30	## Workflow
31
32	```mermaid
33	flowchart TD
34	A[Job failure reported] --> B{MCP Admin API available?}
35	B -->\|yes\| C[Use list_jobs_runs to get history]
36	B -->\|no\| D[Ask user for logs and run_results.json]
37	C --> E[Use get_job_run_error for details]
38	D --> F[Classify error type]
39	E --> F
40	F --> G{Error type?}
41	G -->\|Infrastructure\| H[Check warehouse, connections, timeouts]
42	G -->\|Code/Compilation\| I[Check git history for recent changes]
43	G -->\|Data/Test Failure\| J[Use discovering-data skill to investigate]
44	H --> K{Root cause found?}
45	I --> K
46	J --> K
47	K -->\|yes\| L[Create branch, implement fix]
48	K -->\|no\| M[Create findings document]
49	L --> N[Add test - prefer unit test]
50	N --> O[Create PR with explanation]
51	M --> P[Document what was checked and next steps]
52	```
53
54	## Step 1: Gather Job Run Information
55
56	### If dbt MCP Server Admin API Available
57
58	Use these tools first - they provide the most comprehensive data:
59
60	\| Tool \| Purpose \|
61	\|------\|---------\|
62	\| `list_jobs_runs` \| Get recent run history, identify patterns \|
63	\| `get_job_run_error` \| Get detailed error message and context \|
64
65	```
66	# Example: Get recent runs for job 12345
67	list_jobs_runs(job_id=12345, limit=10)
68
69	# Example: Get error details for specific run
70	get_job_run_error(run_id=67890)
71	```
72
73	### Without MCP Admin API
74
75	Ask the user to provide these artifacts:
76
77	1. Job run logs from dbt Cloud UI (Debug logs preferred)
78	2. `run_results.json` - contains execution status for each node
79
80	To get the `run_results.json`, generate the artifact URL for the user:
81	```
82	https://<DBT_ENDPOINT>/api/v2/accounts/<ACCOUNT_ID>/runs/<RUN_ID>/artifacts/run_results.json?step=<STEP_NUMBER>
83	```
84
85	Where:
86	- `<DBT_ENDPOINT>` - The dbt Cloud endpoint. e.g
87	- `cloud.getdbt.com` for the US multi-tenant platform (there are other endpoints for other regions)
88	- `ACCOUNT_PREFIX.us1.dbt.com` for the cell-based platforms (there are different cell endpoints for different regions and cloud providers)
89	- `<ACCOUNT_ID>` - The dbt Cloud account ID
90	- `<RUN_ID>` - The failed job run ID
91	- `<STEP_NUMBER>` - The step that failed (e.g., if step 4 failed, use `?step=4`)
92
93	Example request:
94	> "I don't have access to the dbt MCP server. Could you provide:
95	> 1. The debug logs from dbt Cloud (Job Run → Logs → Download)
96	> 2. The run_results.json - open this URL and copy/paste or upload the contents:
97	> `https://cloud.getdbt.com/api/v2/accounts/12345/runs/67890/artifacts/run_results.json?step=4`
98
99	## Step 2: Classify the Error
100
101	\| Error Type \| Indicators \| Primary Investigation \|
102	\|------------\|-----------\|----------------------\|
103	\| Infrastructure \| Connection timeout, warehouse error, permissions \| Check warehouse status, connection settings \|
104	\| Code/Compilation \| Undefined macro, syntax error, parsing error \| Check git history for recent changes, use LSP tools \|
105	\| Data/Test Failure \| Test failed with N results, schema mismatch \| Use `discovering-data` skill to query actual data \|
106
107	## Step 3: Investigate Root Cause
108
109	### For Infrastructure Errors
110
111	1. Check job configuration (timeout settings, execution steps, etc.)
112	2. Look for concurrent jobs comp

People who liked this also viewed

6 picks

Type