Zenn
🙌

【dbt Docs】Guides - Debugging errors

2022/03/17に公開
dbt
tech

Debugging errors

https://docs.getdbt.com/docs/guides/debugging-errors

General process of debugging　（一般的なデバッグ手順）

デバッグの方法を学ぶことはスキルであり、自分の役割を果たすために必要なものです。

  • エラーメッセージを読むこと：dbtでは、エラーメッセージはできるだけわかりやすくなるようにしている。エラーメッセージには、エラーの種類（後述）とエラー発生対象のファイル名が含まれる。
  • 原因となったことが判明しているファイルを検査し、すぐに修正できることがあるかどうかを確認します。
  • 問題の切り分け - あるモデルを実行したり、切り戻ししてみたり
  • コンパイル済みのSQLファイルを調査する
    • target/compiledには、select句があるので、それを実行して調べる
    • target/runには、モデル構築したクエリが保存されている（ create ... ）
    • logs/dbt.logをみて実行したクエリや追加情報を調べる。最新のエラーログはファイル下部に追記されているのでそこをみる
    • dbtCloud users : 「Details」タブを見る
    • dbt CLI users : コードエディタでアコーディオンで隠れてることもあるので注意
  • どうしても行き詰まったときは、助けを求めてみましょう。その前に、他の人が問題を素早く診断できるように、時間をかけて質問をよく書きましょう。

Types of errors

dbt runを実行した際には、以下のようなエラーがあります。

Step Description Error type
Initialize dbtプロジェクトであるか？DWHに接続できるか？ Runtime Error
Parsing .sqlファイル内のJinjaの記述に問題がないか？ .ymlのファイルに問題ないか？ Compilation Erro
Graph validateion 依存関係をグラフにまとめる。それが非循環的であることを確認する。 Dependency Error
SQL execution モデルの実行時 Database Error

いかにそれぞれのErrorの詳細を列挙します。※すべてを網羅しているわけではない

Runtime Errors

※　dbtCloudの場合は、多分ほとんど起きないはず

Not a dbt project

Running with dbt=0.17.1
Encountered an error:
Runtime Error
  fatal: Not a dbt project (or any of the parent directories). Missing dbt_project.yml file

Could not find profile

Running with dbt=0.17.1

Encountered an error:
Runtime Error
  Could not run dbt
  Could not find profile named 'jaffle_shops'

Failed to connect

Encountered an error:
Runtime Error
  Database error while listing schemas in database "analytics"
  Database Error
    250001 (08001): Failed to connect to DB: your_db.snowflakecomputing.com:443. Incorrect username or password was specified

Invalid dbt_project.yml file

Encountered an error while reading the project:
ERROR: Runtime Error
at path []: Additional properties are not allowed ('hello' was unexpected)

Error encountered in /Users/alice/jaffle-shop-dbt/dbt_project.yml
Encountered an error:
Runtime Error
Could not run dbt

Compilation Errors

注意： dbtCloudでは、エディタ画面で赤く警告が出る。dbt CLIでは、dbt runやdbt compileで初めて顕在化

Invalid ref function

$ dbt run -s customers
Running with dbt=0.17.1

Encountered an error:
Compilation Error in model customers (models/customers.sql)
  Model 'model.jaffle_shop.customers' (models/customers.sql) depends on a node named 'stg_customer' which was not found

Invalid Jinja

$ dbt run
Running with dbt=0.17.1
Compilation Error in macro (macros/cents_to_dollars.sql)
  Reached EOF without finding a close tag for macro (searched from line 1)

Invalid YAML

$ dbt run
Running with dbt=0.17.1

Encountered an error:
Compilation Error
  Error reading jaffle_shop: schema.yml - Runtime Error
    Syntax error near line 5
    ------------------------------
    2  |
    3  | models:
    4  | - name: customers
    5  |     columns:
    6  |       - name: customer_id
    7  |         tests:
    8  |           - unique

    Raw Error:
    ------------------------------
    mapping values are not allowed in this context
      in "<unicode string>", line 5, column 12

Incorrect YAML spec

YAMLの構造は正しいのですが（つまりYAMLパーサーはこれをpythonの辞書に変換できる）、dbtが認識しないキーがあります。

$ dbt run
Running with dbt=0.17.1

Encountered an error:
Compilation Error
  Invalid models config given in models/schema.yml @ models: {'name': 'customers', 'hello': 'world', 'columns': [{'name': 'customer_id', 'tests': ['unique', 'not_null']}], 'original_file_path': 'models/schema.yml', 'yaml_key': 'models', 'package_name': 'jaffle_shop'} - at path []: Additional properties are not allowed ('hello' was unexpected)

Dependency Errors

$ dbt run
Running with dbt=0.17.1-rc

Encountered an error:
Found a cycle: model.jaffle_shop.customers --> model.jaffle_shop.stg_customers --> model.jaffle_shop.customers
  • ref機能を更新して、この循環を修正する
  • 現在のモデルを参照する必要がある場合は、代わりに {{ this }} 変数を使用します。

Database Errors

一番、エラー原因を特定するのが大変なエラー。
これらのエラーはデータウェアハウスから発生し、dbtはそのメッセージを受け渡します。これらのエラーをデバッグするには、データウェアハウスのドキュメント（SnowflakeのドキュメントやBigQueryのドキュメントなど）を使用する必要があるかもしれません。

$ dbt run
...
Completed with 1 error and 0 warnings:

Database Error in model customers (models/customers.sql)
  001003 (42000): SQL compilation error:
  syntax error line 14 at position 4 unexpected 'from'.
  compiled SQL at target/run/jaffle_shop/models/customers.sql

大抵の場合（9割）は、SQLの構文エラー

  • 問題のあるファイルを開く

    • dbtCloud 問題のあるファイルを開く。
    • dbt CLI: コンパイル済みのSQLを開く target/run/jaffle_shop/models/customers.sql

  • 問題の切り分けのために、そのSQLを再度実行する（DWH上とかで）

    • dbtCloud Run SQLボタン
    • dbt CLI: コンパイル済みSQLをコピペして、DWH製品のコンソールで実行し、エラー箇所を特定する

  • 問題箇所を修正

  • 失敗したモデルを再度実行

  • データベース内のオブジェクトを一覧表示するイントロスペクティブクエリ

  • スキーマを作成するためのクエリ

  • pre-hookss, post-hooks, on-run-end hooks and on-run-start hooks

  • インクリメンタルモデル、スナップショットの場合：マージ、アップデート、インサートステートメント

このような場合、dbtが実行したすべてのクエリを含むログをチェックする必要があります。

  • dbt Cloud: Detailsボタンで、logs/dbt.logをチェックする
  • dbt CLI: logs/dbt.logを確認する

Common pitfalls（よくある落とし穴）

run sql vs dbt run

(dbtCloudのときのみ）

Forgetting to save files before running

ファイルセーブする前に実行したとき

Editing compiled files

コンパイル済みのファイルを編集した場合に、反映しないとかはよくある。target/以下を触らないようにする

Discussion