signalpilot-labs dbt Debugging Skill
1. Duplicate YML Patches (VERY COMMON)
dbt fails with "Duplicate patch" when the same model appears in multiple YML files. Fix in ONE pass:
- Glob
models/**/*.ymlto find all YML files - Keep the entry with the full contract (descriptions, refs, columns) - usually in a subdirectory YML
- Remove the duplicate from
schema.yml(which typically only has tests)
2. Ref Not Found
When a missing ref() has a same-name physical relation, add an ephemeral wrapper selecting that fully qualified relation because this repairs graph resolution without changing identity. Do not redirect an existing ref() or source to a different relation because that changes population.
3. Raw-Relation Name Collision
Do not create a persistent model with the same qualified name as a raw relation because materialization overwrites its input. Add a missing source schema only when it qualifies the same configured identifier because that preserves identity.
4. current_date Fix
If dbt_project_map warns about current_date usage:
- Call
get_date_boundaries- find the column marked "USE THIS" - Replace
current_date/now()with(SELECT MAX(<col>) FROM {{ ref('<table>') }}) - For package models: create
models/<name>.sql, paste full SQL, replace current_date
Keep current_date where a YML description anchors logic to the present ('current fiscal year', 'as of today', 'active now') - the warning is about stale date spines and date caps, not present-anchored business rules.
5. DuckDB Error Messages
| Error | Fix |
|---|---|
invalid date field format |
STRPTIME(col, '%d/%m/%Y')::DATE |
Table does not exist |
Check actual names with describe_table |
column not found |
Check exact names - case matters in DuckDB |
Cannot mix TIMESTAMP and INTEGER |
Cast both args to same type |
No function matches DOUBLE / VARCHAR |
Add explicit CAST() |
fivetran_utils is undefined |
Run dbt deps (only if packages.yml exists) |
6. Package Model Build Failures
If dbt run fails on a model inside dbt_packages/ with a type error
(e.g., date_trunc on an INTEGER, No function matches), you MUST fix
the package SQL file directly. The sandbox has no internet, so you cannot
reinstall the package. Read the failing SQL, find the type mismatch, and
add the appropriate CAST or conversion (e.g., to_timestamp(epoch_col)
for epoch integers, CAST(col AS DATE) for type mismatches). Broken
upstream models block everything downstream.
7. Zero-Row Model
Treat a successful zero-row relation as valid unless the task, YML, prebuild_state.md, or complete sibling requires rows because empty population is not a build failure. Diagnose filters and joins only after that evidence exists. Do not redirect a configured source merely to populate it.
8. Fan-Out (Too Many Rows)
- Diagnose:
SELECT join_key, COUNT(*) FROM right_table GROUP BY 1 HAVING COUNT(*) > 1 - Fix A: pre-aggregate right table before joining
- Fix B:
SELECT DISTINCT(if valid for the grain) - Fix C:
ROW_NUMBER()dedup pattern