dbt Troubleshooting: Common Errors and How to Fix Them

dbt spans multiple layers: SQL transformations, Jinja, adapter-mediated connections, selection rules, and tests. Errors look different in each layer, and without proper isolation you can burn a lot of time chasing the wrong cause.

This article organizes the failure patterns that show up most often in the field, layer by layer, and offers reproducible diagnostic steps and reliable fixes. It also covers the command differences and incremental requirements that the Analytics Engineer exam likes to test.

Isolating profile and connection errors

Start by verifying that profiles.yml and the adapter line up. Use dbt debug to validate the profile name in dbt_project.yml, the target in profiles.yml, the authentication method, and whether the adapter plugin is installed.

Errors caused by network or privilege issues are typical at the database connection layer. Use the vocabulary of the error message — authentication failure, missing schema, insufficient role — to localize the problem, then fall back to a minimal-configuration connection test.

• Runtime Error: Could not find profile named 'xxx' → the profile name in dbt_project.yml does not match the key in ~/.dbt/profiles.yml
• Database Error: Authentication failed / invalid credentials → re-check environment variables and key-file references for credentials
• Adapter Error: Missing required dependency → the adapter is not installed. Example: pip install dbt-bigquery / dbt-snowflake
• Database Error: schema does not exist → schema creation privilege is required upfront, or add CREATE SCHEMA to an on-run-start hook in dbt

Initial response flow for connection issues

Minimal profiles.yml example (Snowflake, using environment variables)

snowflake_profile:
  target: dev
  outputs:
    dev:
      type: snowflake
      account: "{{ env_var('SNOWFLAKE_ACCOUNT') }}"
      user: "{{ env_var('SNOWFLAKE_USER') }}"
      password: "{{ env_var('SNOWFLAKE_PASSWORD') }}"
      role: ANALYST
      database: ANALYTICS
      warehouse: TRANSFORMING
      schema: DEV
      threads: 8
      client_session_keep_alive: true

Failures from selection rules and command differences

dbt's node selection involves ref() dependencies, tags, and paths. No nodes selected means the selector resolved to an empty set. Visualize the target set with dbt ls before running the production command to dramatically cut down on incidents.

The difference between run and build is a frequent exam topic. build runs models, tests, snapshots, seeds, and exposures together in dependency order. build is the default path in CI, but you need to understand its behavior around unintended seed overwrites and halts on test failures.

• No nodes selected → recheck the selector: dbt ls -s <selector>
• Found duplicate model name → package collision. Resolve with models: +schema / +alias, or prefix with the package name
• State-based selection returns zero rows → the state path is wrong when using dbt run -s state:modified --state path/to/artifacts

Example of target visualization and safe selection

# First confirm the targets
/dbt ls -s tag:daily +
# Only the changed nodes (state:modified)
/dbt ls -s state:modified --state ./target

# Real run (include downstream dependencies)
/dbt build -s tag:daily+ --fail-fast

# Alias to avoid package collisions (example from dbt_project.yml)
models:
  my_pkg:
    +alias: pkg__{{ model.name }}

Incremental model failures and safe reruns

Incremental looks convenient but produces missing rows or duplicates when unique_key or the is_incremental() condition is ambiguous. The merge strategy effectively requires a unique_key. The key is a condition that does not break in CI or production runs that mix full refreshes.

Schema changes behave differently based on the on_schema_change setting and whether the adapter supports it. Unsupported combinations raise a Database Error, so make the sync policy explicit and initialize with --full-refresh when necessary.

• merge without unique_key → runtime error or duplicate rows
• Nondeterministic boundary timestamp in is_incremental() → missing rows or duplicates on rerun
• on_schema_change unsupported / mismatched → ALTER / REPLACE fails
• No partition column specified (on warehouses that support it) → excessive scans and higher costs

Robust incremental model example

{{ config(
    materialized='incremental',
    unique_key='id',
    on_schema_change='sync_all_columns'
) }}

with src as (
  select * from {{ ref('stg_events') }}
)

select
  id,
  event_ts,
  payload
from src
{% if is_incremental() %}
where event_ts > (
  select coalesce(max(event_ts), '1970-01-01') from {{ this }}
)
{% endif %}

Privilege, schema, and quoting pitfalls

If the target schema does not exist or the role cannot create it, the model fails before it is even created. In production, grant explicit CREATE / USAGE privileges to the deployment role, or automate CREATE SCHEMA in an on-run-start hook for the first run only.

Identifier case sensitivity and reserved words behave differently per adapter. Standardize quoting for identifier and schema via the dbt quoting setting, and pin the name explicitly with alias — it is the safe approach.

• schema does not exist → create the schema in advance, or create it via run-operation on the first run
• permission denied → grant read and create privileges separately. At minimum: USAGE / CREATE / SELECT / INSERT / UPDATE / DELETE
• Case sensitivity drift → stabilize by setting quoting.identifier to true and pinning with alias

Stabilizing quoting and schema (profiles.yml / model config)

# profiles.yml example (always quote identifiers)
quoting:
  database: false
  schema: true
  identifier: true

# Pin the alias on the model side (top of models/*.sql)
{{ config(alias='fact_events', schema='prod') }}

Failures originating from Jinja, macros, and packages

A Compilation Error is a failure during the Jinja interpretation stage. The cause is usually an undefined variable or macro, or a type mismatch — and dbt parse catches these early. Harden vars by providing defaults.

Missing package-sourced macros are typically caused by not running dbt deps or by a version mismatch. Revisit the pins in packages.yml and the dispatch rules used when names collide.

• Compilation Error: 'my_var' is undefined → use var('my_var', 'default')
• Macro not found → check packages.yml and run dbt deps
• adapter.dispatch resolution failure → confirm that macro naming and package_namespace line up

Example: vars defaults and package management

# Safe vars reference inside a model
select * from {{ ref('stg_users') }} where country = '{{ var('country', 'JP') }}'

# packages.yml (example)
packages:
  - package: dbt-labs/dbt_utils
    version: ">=1.0.0,<2.0.0"

# Verification
/dbt deps
/dbt parse

Handling failures around tests, source freshness, and operations

When a test fails, first confirm whether it is detecting per the quality spec. Decide whether to absorb periods where NULLs or duplicates are tolerated, or the handling of exceptions, on the model side or via conditions on the test side.

source freshness fails when the max latency is exceeded. Align the scheduler with the ingest cycle, and pipe the JSON output into your monitoring stack for effective operations.

• Identify failing rows with dbt test --store-failures
• Hook dbt source freshness --output json into monitoring
• Seeds easily drift due to type and quoting settings. Reconcile with --full-refresh.

Practical snippets for tests, freshness, and CI

# tests/schema.yml (example)
models:
  - name: dim_users
    tests:
      - unique:
          column_name: user_id
      - not_null:
          column_name: user_id

sources:
  - name: app
    tables:
      - name: events
        freshness:
          warn_after: {count: 12, period: hour}
          error_after: {count: 24, period: hour}
          loaded_at_field: event_ts

# In CI, run everything together with build
git diff --name-only | xargs -I{} echo {}
/dbt build --select state:modified+ --state ./target --fail-fast --warn-error
/dbt source freshness --select source:app.events --output json

Check Your Understanding

Frequently Asked Questions