dbt トラブルシューティング: よくあるエラーと対処

dbtはSQL変換、Jinja、アダプター経由の接続、選択ルール、テストといった複数レイヤーが絡みます。エラーは層ごとに性質が異なり、正しく切り分けないと時間を失いがちです。

この記事では、現場で多い失敗パターンを層ごとに整理し、再現性のある確認手順と安定解を提示します。Analytics Engineer試験で問われるコマンド差分やインクリメンタルの要件にも触れます。

プロファイル・接続エラーの切り分け

最初に確認すべきはprofiles.ymlとアダプターの整合です。dbt_project.ymlのprofile名、profiles.ymlのターゲット、認証方式、そしてアダプタープラグインの導入状況をdbt debugで検証します。

ネットワークや権限に起因するエラーはdb接続レイヤーの典型です。認証エラー、スキーマ未作成、ロール不足など、エラーメッセージの語彙で大枠を特定し、最小構成での接続テストへ切り戻します。

• Runtime Error: Could not find profile named 'xxx' → dbt_project.ymlのprofile名と~/.dbt/profiles.ymlのキー名不一致
• Database Error: Authentication failed / invalid credentials → 認証情報の環境変数やキーファイル参照を再確認
• Adapter Error: Missing required dependency → アダプター未導入。例: pip install dbt-bigquery / dbt-snowflake
• Database Error: schema does not exist → 事前にスキーマ作成権限が必要、あるいはdbtでon-run-startにCREATE SCHEMAを付与

接続トラブルの初動フロー

最低限のprofiles.yml例（Snowflakeの例。環境変数併用）

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

選択ルールとコマンド差分で起こる失敗

dbtのノード選択はref()依存やタグ、パスが絡みます。No nodes selectedはセレクタが空集合になったサインです。dbt lsで対象を先に可視化してから本番コマンドを流すと事故が減ります。

runとbuildの違いは試験でも頻出です。buildはmodels, tests, snapshots, seeds, exposuresを依存順に包括実行します。CIではbuildが既定路線ですが、意図せぬseed上書きやtest失敗による停止を理解しておく必要があります。

• No nodes selected → セレクタ再確認: dbt ls -s <selector>
• Found duplicate model name → パッケージ衝突。models: +schema/+alias で解消、またはpackage名をprefix化
• State-based選択で対象0件 → dbt run -s state:modified --state path/to/artifacts を使う際のstate参照先誤り

対象可視化と安全な選択の例

# まずは対象を確認
/dbt ls -s tag:daily +
# 変更分のみ（state:modified）
/dbt ls -s state:modified --state ./target

# 本実行（依存先も含める）
/dbt build -s tag:daily+ --fail-fast

# パッケージ衝突回避のエイリアス（dbt_project.ymlの例）
models:
  my_pkg:
    +alias: pkg__{{ model.name }}

インクリメンタルモデルの失敗と安全な再実行

インクリメンタルは一見便利ですが、unique_keyやis_incremental()の条件式が曖昧だと取り込み漏れや重複を生みます。merge戦略ではunique_keyがほぼ必須です。フルリフレッシュが混在するCI/本番でも壊れない条件式が鍵です。

スキーマ変更はon_schema_changeの設定と、アダプターが対応しているかで挙動が変わります。未対応の組み合わせではDatabase Errorが出るため、同期ポリシーを明示し、必要に応じて--full-refreshで初期化します。

• unique_key未設定のmerge → 実行時エラー、または重複行
• is_incremental()の境界日時が非決定的 → 再実行で抜け/重複
• on_schema_change未対応/不一致 → ALTER/REPLACEの失敗
• パーティション列未指定（対応DWH） → スキャン過多・コスト増

堅牢なインクリメンタルモデル例

{{ 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 %}

権限・スキーマ・クオート設定の罠

作成先スキーマが存在しない、あるいは作成権限がない場合、モデル作成前に失敗します。運用ではデプロイ用ロールにCREATE/USAGE権限を明確に付与し、初回のみon-run-startでCREATE SCHEMAを自動化する方法もあります。

識別子の大文字小文字や予約語はアダプターごとに扱いが異なります。dbtのquoting設定でidentifier/schemaの引用有無を統一し、aliasで明示的に名前を固定するのが安全です。

• schema does not exist → 事前にスキーマを作るか、初回run-operationで作成
• permission denied → 参照と作成系権限を分けて付与。最低限USAGE/CREATE/SELECT/INSERT/UPDATE/DELETE
• 大文字小文字ゆらぎ → quoting.identifierをtrueにして安定化、aliasで固定

クオートとスキーマの安定化（profiles.yml / モデル設定）

# profiles.ymlの例（識別子を常に引用）
quoting:
  database: false
  schema: true
  identifier: true

# モデル側でのエイリアス固定（models/*.sqlの先頭）
{{ config(alias='fact_events', schema='prod') }}

Jinja/マクロ/パッケージ起因の失敗

Compilation ErrorはJinja解釈段階の失敗です。未定義の変数やマクロ、型不整合が原因のことが多く、dbt parseで早期に発見できます。varsはデフォルトを与えて堅牢化します。

パッケージ由来のマクロ未検出はdbt deps未実行やバージョン不整合が典型です。packages.ymlのピン留め、名称衝突時のdispatchルールを見直します。

• Compilation Error: 'my_var' is undefined → var('my_var', 'default') を使う
• Macro not found → packages.ymlを確認しdbt depsを実行
• adapter.dispatchの解決失敗 → マクロ命名とpackage_namespaceの整合を確認

varsのデフォルト/パッケージ管理の例

# モデル内での安全なvars参照
select * from {{ ref('stg_users') }} where country = '{{ var('country', 'JP') }}'

# packages.yml（一例）
packages:
  - package: dbt-labs/dbt_utils
    version: ">=1.0.0,<2.0.0"

# 検証
/dbt deps
/dbt parse

テスト・ソース鮮度・運用時の失敗対応

テスト失敗は品質の仕様通りに検知しているかをまず確認します。NULLや重複が許容される期間・例外の取り扱いをモデル側で吸収するか、test側で条件を与えるかを決めます。

source freshnessは最大遅延を超えると失敗します。スケジューラと取り込みサイクルの整合を取り、運用ではJSON出力を監視に流すと効果的です。

• dbt test --store-failuresで不合格行を特定
• dbt source freshness --output jsonを監視に連携
• seedは型とクオート設定で差分が出やすい。--full-refreshで整合させる

テスト/鮮度/CIの実用スニペット

# tests/schema.yml（一例）
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

# CIでは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

問題で確認

よくある質問