debugging-dbt-errors

Name: debugging-dbt-errors
Author: AltimateAI

22installs7forks

How to install debugging-dbt-errors?

altimateai/data-engineering-skills/debugging-dbt-errors

$npx -y skills add AltimateAI/data-engineering-skills --skill debugging-dbt-errors

Installs into the current project.

Summary

Debugs and fixes dbt errors systematically. Use when working with dbt errors for: (1) Task mentions "fix", "error", "broken", "failing", "debug", "wrong", or "not working" (2) Compilation Error, Database Error, or test failures occur (3) Model produces incorrect output or unexpec

Files · 1

View on GitHub

SKILL.md

1	# dbt Troubleshooting
2
3	Read the full error. Check upstream first. ALWAYS run `dbt build` after fixing.
4
5	## Critical Rules
6
7	1. ALWAYS run `dbt build` after fixing - compile is NOT enough to verify the fix
8	2. If fix fails 3+ times, stop and reassess your entire approach
9	3. Verify data after build - build passing doesn't mean output is correct
10
11	## Workflow
12
13	### 1. Get the Full Error
14
15	```bash
16	dbt compile --select <model_name>
17	# or
18	dbt build --select <model_name>
19	```
20
21	Read the COMPLETE error message. Note the file, line number, and specific error.
22
23	### 2. Inspect Actual Data (For Data Issues)
24
25	Before fixing "wrong output" or "incorrect results", query the actual data:
26
27	```bash
28	# Preview current output
29	dbt show --select <model_name> --limit 20
30
31	# Check specific values with inline query
32	dbt show --inline "select * from {{ ref('model_name') }} where <condition>" --limit 10
33
34	# Compare with expected - look for patterns
35	dbt show --inline "select column, count(*) from {{ ref('model_name') }} group by 1 order by 2 desc" --limit 10
36	```
37
38	Understand what's wrong before attempting to fix it.
39
40	### 3. Read Compiled SQL
41
42	```bash
43	cat target/compiled/<project>/<path>/<model_name>.sql
44	```
45
46	See the actual SQL that will run.
47
48	### 4. Analyze Error Type
49
50	\| Error Type \| Look For \|
51	\|------------\|----------\|
52	\| Compilation Error \| Jinja syntax, missing refs, YAML issues \|
53	\| Database Error \| Column not found, type mismatch, SQL syntax \|
54	\| Dependency Error \| Missing model, circular reference \|
55
56	### 5. Check Upstream Models
57
58	```bash
59	# Find what this model references
60	grep -E "ref\(\|source\(" models/<path>/<model_name>.sql
61
62	# Read upstream model to verify columns
63	cat models/<path>/<upstream_model>.sql
64	```
65
66	Many errors come from upstream changes, not the current model.
67
68	### 6. Apply Fix
69
70	Common fixes:
71
72	\| Error \| Fix \|
73	\|-------\|-----\|
74	\| Column not found \| Check upstream model's output columns \|
75	\| Ambiguous column \| Add table alias: `table.column` \|
76	\| Type mismatch \| Add explicit `CAST()` \|
77	\| Division by zero \| Use `NULLIF(divisor, 0)` \|
78	\| Jinja error \| Check matching `{{ }}` and `{% %}` \|
79
80	### 7. Rebuild (MANDATORY)
81
82	```bash
83	dbt build --select <model_name>
84	```
85
86	3-Failure Rule: If build fails 3+ times, STOP. Step back and:
87	1. Re-read the original error
88	2. Check if your entire approach is wrong
89	3. Consider alternative solutions
90
91	### 8. Verify Fix
92
93	```bash
94	# Preview the data
95	dbt show --select <model_name> --limit 10
96
97	# Run tests
98	dbt test --select <model_name>
99	```
100
101	### 9. Re-review Logic Against Requirements
102
103	After fixing, re-read the original request and verify:
104	- Does the output match what the user asked for?
105	- Are the column names exactly as requested?
106	- Is the calculation logic correct per the requirements?
107	- Did you solve the actual problem, not just make the error go away?
108
109	### 10. Check Downstream Impact
110
111	```bash
112	# Find downstream models
113	grep -r "ref('<model_name>')" models/ --include="*.sql"
114
115	# Rebuild downstream
116	dbt build --select <model_name>+
117	```
118
119	## Error Categories
120
121	### Compilation Errors
122	- Check Jinja syntax: matching `{{ }}` and `{% %}`
123	- Verify macro arguments
124	- Check YAML indentation
125
126	### Database Errors
127	- Read compiled SQL in `target/compiled/`
128	- Check column names against upstream
129	- Verify data types
130
131	### Test Failures
132	- Read the test SQL to understand what it checks
133	- Compare your model output to expected behavior
134	- Check column names, data types, NULL handling
135
136	## Anti-Patterns
137
138	- Making random changes without understanding the error
139	- Assuming the current model is wrong before checking upstream
140	- Not reading the FULL error message
141	- Declaring "fixed" without running build
142	- Getting stuck making small tweaks instead of reassessing

People who liked this also viewed

6 picks

Type

debugging-dbt-errors

22installs7forks

View on GitHub

How to install debugging-dbt-errors?

altimateai/data-engineering-skills/debugging-dbt-errors

$npx -y skills add AltimateAI/data-engineering-skills --skill debugging-dbt-errors

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# dbt Troubleshooting
2
3	Read the full error. Check upstream first. ALWAYS run `dbt build` after fixing.
4
5	## Critical Rules
6
7	1. ALWAYS run `dbt build` after fixing - compile is NOT enough to verify the fix
8	2. If fix fails 3+ times, stop and reassess your entire approach
9	3. Verify data after build - build passing doesn't mean output is correct
10
11	## Workflow
12
13	### 1. Get the Full Error
14
15	```bash
16	dbt compile --select <model_name>
17	# or
18	dbt build --select <model_name>
19	```
20
21	Read the COMPLETE error message. Note the file, line number, and specific error.
22
23	### 2. Inspect Actual Data (For Data Issues)
24
25	Before fixing "wrong output" or "incorrect results", query the actual data:
26
27	```bash
28	# Preview current output
29	dbt show --select <model_name> --limit 20
30
31	# Check specific values with inline query
32	dbt show --inline "select * from {{ ref('model_name') }} where <condition>" --limit 10
33
34	# Compare with expected - look for patterns
35	dbt show --inline "select column, count(*) from {{ ref('model_name') }} group by 1 order by 2 desc" --limit 10
36	```
37
38	Understand what's wrong before attempting to fix it.
39
40	### 3. Read Compiled SQL
41
42	```bash
43	cat target/compiled/<project>/<path>/<model_name>.sql
44	```
45
46	See the actual SQL that will run.
47
48	### 4. Analyze Error Type
49
50	\| Error Type \| Look For \|
51	\|------------\|----------\|
52	\| Compilation Error \| Jinja syntax, missing refs, YAML issues \|
53	\| Database Error \| Column not found, type mismatch, SQL syntax \|
54	\| Dependency Error \| Missing model, circular reference \|
55
56	### 5. Check Upstream Models
57
58	```bash
59	# Find what this model references
60	grep -E "ref\(\|source\(" models/<path>/<model_name>.sql
61
62	# Read upstream model to verify columns
63	cat models/<path>/<upstream_model>.sql
64	```
65
66	Many errors come from upstream changes, not the current model.
67
68	### 6. Apply Fix
69
70	Common fixes:
71
72	\| Error \| Fix \|
73	\|-------\|-----\|
74	\| Column not found \| Check upstream model's output columns \|
75	\| Ambiguous column \| Add table alias: `table.column` \|
76	\| Type mismatch \| Add explicit `CAST()` \|
77	\| Division by zero \| Use `NULLIF(divisor, 0)` \|
78	\| Jinja error \| Check matching `{{ }}` and `{% %}` \|
79
80	### 7. Rebuild (MANDATORY)
81
82	```bash
83	dbt build --select <model_name>
84	```
85
86	3-Failure Rule: If build fails 3+ times, STOP. Step back and:
87	1. Re-read the original error
88	2. Check if your entire approach is wrong
89	3. Consider alternative solutions
90
91	### 8. Verify Fix
92
93	```bash
94	# Preview the data
95	dbt show --select <model_name> --limit 10
96
97	# Run tests
98	dbt test --select <model_name>
99	```
100
101	### 9. Re-review Logic Against Requirements
102
103	After fixing, re-read the original request and verify:
104	- Does the output match what the user asked for?
105	- Are the column names exactly as requested?
106	- Is the calculation logic correct per the requirements?
107	- Did you solve the actual problem, not just make the error go away?
108
109	### 10. Check Downstream Impact
110
111	```bash
112	# Find downstream models
113	grep -r "ref('<model_name>')" models/ --include="*.sql"
114
115	# Rebuild downstream
116	dbt build --select <model_name>+
117	```
118
119	## Error Categories
120
121	### Compilation Errors
122	- Check Jinja syntax: matching `{{ }}` and `{% %}`
123	- Verify macro arguments
124	- Check YAML indentation
125
126	### Database Errors
127	- Read compiled SQL in `target/compiled/`
128	- Check column names against upstream
129	- Verify data types
130
131	### Test Failures
132	- Read the test SQL to understand what it checks
133	- Compare your model output to expected behavior
134	- Check column names, data types, NULL handling
135
136	## Anti-Patterns
137
138	- Making random changes without understanding the error
139	- Assuming the current model is wrong before checking upstream
140	- Not reading the FULL error message
141	- Declaring "fixed" without running build
142	- Getting stuck making small tweaks instead of reassessing

People who liked this also viewed

6 picks

Type