排查 dbt 错误

返回指南故障排查 · dbt 平台 · 入门目录

通用排错流程

调试是一项值得学习的技能，能帮助你更好地完成工作。

阅读错误消息。dbt维护者尽量提供有用的错误信息，通常包含错误类型以及出错文件；错误类型会在后文说明。
检查已知导致问题的文件，判断是否能直接修复。
隔离问题，例如一次只运行一个模型，或撤销引发故障的修改。
熟悉编译文件与日志：
- target/compiled包含可在任意查询编辑器中执行的select语句。
- target/run包含dbt构建模型时实际执行的SQL。
- logs/dbt.log包含dbt执行的全部查询与额外日志，最近的错误位于文件末尾。
- dbt用户可使用上述文件，也可以查看命令输出中的Details选项卡。
- dbt v1用户请注意：代码编辑器可能在文件树中隐藏这些文件，参见VSCode帮助。
如果确实无法解决，可以求助。提问前先认真整理问题，便于他人快速诊断。

错误类型

下面列出一些常见错误。首先了解 dbt 在执行如下命令时的内部过程，会有所帮助： dbt run.

阶段	说明	错误类型
初始化	检查是否为dbt项目，以及是否能够连接数据仓库。	`Runtime Error`
解析	检查`.sql`文件中的Jinja片段及`.yml`文件是否有效。	`Compilation Error`
依赖图验证	将依赖关系编译为图，并检查是否无环。	`Dependency Error`
SQL执行	运行模型。	`Database Error`

下面介绍其中一些错误及其调试方法。注意：这里并未涵盖所有错误。

运行时错误

注意：如果使用 Studio IDE 开发项目，通常不会遇到这些错误。

不是 dbt 项目

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

报告代码问题

调试方法

运行pwd确认所在目录是否正确，不正确时用cd切换。
确认项目根目录存在dbt_project.yml。可以用ls列出文件，也可以在编辑器的文件树中检查。

找不到 profile

Running with dbt=1.7.1

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

报告代码问题

调试方法

检查dbt_project.yml中的profile:。例如，以下项目使用jaffle_shops，注意复数形式：

dbt_project.yml

profile: jaffle_shops # note the plural

报告代码问题

检查profiles.yml中的profile名称。以下名称为jaffle_shop，注意单数形式：

profiles.yml

jaffle_shop: # this does not match the profile: key
  target: dev

  outputs:
    dev:
      type: postgres
      schema: dbt_alice
      ... # other connection details

报告代码问题

修改两处，使名称一致。
找不到profiles.yml时，运行dbt debug --config-dir：

$ dbt debug --config-dir
Running with dbt=1.7.1
To view your profiles.yml file, run:

open /Users/alice/.dbt

报告代码问题

然后按实际路径执行open /Users/alice/.dbt，检查是否存在profiles.yml；若没有，按相关文档创建。

连接失败

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.

报告代码问题

调试方法

打开profiles.yml；不确定位置时，运行dbt debug --config-dir。
确认凭据正确，必要时与数据库管理员核对。
更新凭据后，运行dbt debug检查连接。

$ dbt debug
Running with dbt=1.7.1
Using profiles.yml file at /Users/alice/.dbt/profiles.yml
Using dbt_project.yml file at /Users/alice/jaffle-shop-dbt/dbt_project.yml

Configuration:
  profiles.yml file [OK found and valid]
  dbt_project.yml file [OK found and valid]

Required dependencies:
 - git [OK found]

Connection:
  ...
  Connection test: OK connection ok

报告代码问题

`dbt_project.yml` 无效

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

报告代码问题

调试方法

打开dbt_project.yml。
找到错误字段，例如消息“’hello‘ was unexpected”中的hello。

dbt_project.yml

name: jaffle_shop
hello: world # this is not allowed

报告代码问题

根据dbt_project.yml参考文档修正问题。
如果文档表明字段有效，用dbt --version确认所用dbt版本是否最新。

编译错误

注意：使用 Studio IDE 开发 dbt 项目时，此错误通常会在命令提示区域显示为红色条。对于 dbt v1 用户，只有运行以下命令后才会检测到： dbt run or dbt compile.

`ref` 引用无效

$ dbt run -s customers
Running with dbt=1.1.0

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

报告代码问题

调试方法

打开models/customers.sql。
使用cmd + f或对应快捷键搜索stg_customer。该引用要求存在stg_customer.sql文件。
改为引用实际模型文件名，本例为stg_customers；或者把模型重命名为stg_customer。

Jinja 无效

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

报告代码问题

调试方法

这里的错误由 Jinja 库返回，dbt 将其直接转交给你。

这个例子是由于忘记了 {% endmacro %} 标签；以下情况也可能产生类似错误：

遗漏闭合的}。
尚未关闭if语句，就先关闭了for循环。

修复方法：

按照错误消息找到出错文件，例如macros/cents_to_dollars.sql。
根据错误消息定位错误。

预防方法：

仅dbt v1：可以使用代码片段自动补全Jinja，例如atom-dbt包。

YAML 无效

dbt 无法将 YAML 转换为有效的字典。

$ dbt run
Running with dbt=1.7.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  |         data_tests:
    8  |           - unique

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

报告代码问题

调试方法

通常与缩进有关；下面是导致该错误的 YAML：


models:
  - name: customers
      columns: # this is indented too far!
      - name: customer_id
        data_tests:
          - unique
          - not_null

报告代码问题

修复方法：

打开出错文件，例如schema.yml。
检查错误消息指出的行，例如第5行。
找到并修正错误。

预防方法：

dbt v1用户可在编辑器中开启缩进参考线，便于检查。
可使用YAML验证器辅助排错。

YAML 不符合配置规范

这是一种略有不同的错误：YAML 结构正确，即解析器能够将其转换为 Python 字典，但其中有一个 dbt 不认识的键。

$ dbt run
Running with dbt=1.7.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)

报告代码问题

调试方法

根据错误消息打开文件，例如models/schema.yml。
搜索被指出的字段，例如“‘hello‘ was unexpected”中的hello。
根据模型属性文档找到有效字段并修正。
如果字段有效，运行dbt --version确认是否使用最新版本。

依赖错误

$ dbt run
Running with dbt=1.7.1-rc

Encountered an error:
Found a cycle: model.jaffle_shop.customers --> model.jaffle_shop.stg_customers --> model.jaffle_shop.customers

报告代码问题

dbt 的依赖图中存在环，必须修复。

修改ref调用，打破循环依赖。
需要引用当前模型时，应使用{{ this }}。

数据库错误

这是最棘手的一类错误。错误来自数据仓库，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

报告代码问题

原文的经验判断是，90% 的情况下问题出在模型 SQL 中。修复方法如下：

打开出错文件：
- dbt：根据错误消息打开模型，本例为models/customers.sql。
- dbt v1：除模型外，再打开编译后的SQL，本例为target/run/jaffle_shop/models/customers.sql。可在编辑器中并排查看。
尝试重新执行SQL，以隔离错误：
- dbt：在模型文件中使用Preview。
- dbt v1：把编译后的查询复制到查询工具中执行，例如Snowflake界面、DataGrip或TablePlus。
修正错误。
重新运行失败的模型。

有时，错误也可能由 dbt 在后台运行的查询引起，包括：

列举数据库对象的内省查询。
创建schema的查询。
pre-hooks、post-hooks、on-run-end与on-run-start钩子。
增量模型与快照中的merge、update和insert语句。

此时应查看日志，其中包含 dbt 执行过的全部查询。

dbt：在命令输出的Details中查看日志，或检查logs/dbt.log。
dbt v1：打开logs/dbt.log。

在日志中定位错误

如果遇到难以理解的Database Error，可以先打开日志文件、清空内容，再只对问题模型执行dbt run，这样日志中只保留所需输出。

常见陷阱

`Preview` 与 `dbt run`

（仅适用于 Studio IDE 用户）

以下两个界面看起来很相似：

Preview执行当前选项卡中的SQL，相当于取出target/compiled中的select语句，在查询编辑器中运行以查看结果。
dbt run则会在数据库中构建关系。

使用 Preview 按钮可在开发模型时直观检查查询结果。不过，必须确保已对所有上游模型执行 dbt run ，否则 dbt 会尝试从尚未构建的对象中查询，即 from 不存在的表和视图。

运行前忘记保存文件

这种情况大家都遇到过：执行命令时，dbt 使用文件最后保存的版本。多数代码编辑器以及 Studio IDE 会在存在未保存更改的文件名旁显示圆点。执行 dbt 命令前，务必按下 cmd + s 或使用等效的保存操作，逐渐养成习惯。

误改编译生成的文件

（dbt v1 用户更容易遇到）

如果刚刚打开了 target/ 目录中的 SQL 文件来排查问题，很容易误改该文件。为避免这种情况，可以调整编辑器设置，让以下目录中的文件显示为灰色： target/ 。这种视觉提示有助于避免误操作。

常见问题

下面这些常见问题有助于调试 dbt 项目：

如何生成 HAR 文件

HTTP Archive（HAR）文件收集浏览器数据，dbt支持团队可用它排查网络或资源问题，其中包括浏览器与服务器之间请求的详细计时信息。

以下说明如何在Google Chrome、Mozilla Firefox、Apple Safari和Microsoft Edge中生成HAR文件。

信息

发送给dbt Labs之前，应移除或隐藏机密信息与个人身份信息。可使用文本编辑器修改文件。

Google Chrome
1. 打开Google Chrome。
2. 点击View –> Developer Tools。
3. 选择Network选项卡。
4. 确认正在录制：红色按钮表示已开始，否则点击Record network log。
5. 勾选Preserve Log。
6. 点击Clear network log（🚫）清空现有日志。
7. 进入出错页面并复现问题。
8. 点击与清除日志按钮同一行的Export HAR下箭头图标，导出HAR文件。
9. 保存HAR文件。
10. 将HAR文件上传到dbt支持工单对话。
Mozilla Firefox
1. 打开Firefox。
2. 打开应用菜单，选择More tools –> Web Developer Tools。
3. 在开发工具中选择Network。
4. 进入出错页面并复现问题；导航时会自动开始录制。
5. 完成后点击Pause/Resume recording network log。
6. 在File列任意位置右键，选择Save All as HAR。
7. 保存HAR文件。
8. 将HAR文件上传到dbt支持工单对话。
Apple Safari
1. 打开Safari。
2. 如果菜单栏没有Develop，进入Safari的Settings。
3. 点击Advanced。
4. 勾选Show features for web developers。
5. 在Develop菜单选择Show Web Inspector。
6. 点击Network。
7. 进入出错页面并复现问题。
8. 完成后点击Export。
9. 保存文件。
10. 将HAR文件上传到dbt支持工单对话。
Microsoft Edge
1. 打开Microsoft Edge。
2. 点击工具栏右侧的Settings and more（…），再选择More tools –> Developer tools。
3. 点击Network。
4. 确认正在录制：红色按钮表示已开始，否则点击Record network log。
5. 进入出错页面并复现问题。
6. 完成后点击Stop recording network log。
7. 点击Export HAR下箭头，或按Ctrl + S导出HAR。
8. 保存HAR文件。
9. 将HAR文件上传到dbt支持工单对话。
补充资源

可观看如何在 Chrome 中生成 HAR 文件视频，了解Chrome中的完整操作。
身份认证过期后重新连接 Snowflake OAuth

通过OAuth将Snowflake连接到dbt平台时，dbt会保存刷新令牌，使Studio IDE、dbt Semantic Layer等工具能够复用凭据，而无需每次重新认证。

运行查询时出现authentication has expired，表示需要续接Snowflake与dbt平台的连接。

解决步骤如下：
1. 从导航菜单进入Your profile。
2. 进入Credentials，选择出现问题的项目。
3. 在User credentials下点击Reconnect Snowflake Account，按单点登录流程重新认证。
Snowflake管理员可以配置刷新令牌有效期，最长90天。

如果仍然报错，请联系support@getdbt.com寻求帮助。
dbt 任务出现 Could not parse dbt_project.yml 错误

作业或开发中出现Could not parse dbt_project.yml: while scanning for...，通常有以下原因：
- YAML解析失败，例如使用Tab缩进或包含导致问题的Unicode字符。
- dbt_project.yml缺少字段或格式错误。
- 项目仓库中不存在dbt_project.yml。
可以考虑以下处理方法：
- 使用YAML解析器或验证器检查缺失字段、格式错误、Tab缩进等解析问题。
- 确认dbt_project.yml确实存在。
识别并修正问题后，重新运行作业。
如何修复 .gitignore 文件？

gitignore文件指定Git应忽略的文件。在项目中，这些文件通常以斜体显示。

如果无法撤销修改、切换分支或提交，常见原因是项目缺少.gitignore，或者该文件缺少必要内容。

修复步骤如下：
1. 在Studio IDE中，将以下内容加入项目的.gitignore：
```
target/
dbt_packages/
logs/
# legacy -- renamed to dbt_packages in dbt v1
dbt_modules/
```
报告代码问题
1. 保存修改，暂不提交。
2. 点击Studio IDE右下角状态按钮旁的三个点。
点击右下角的三个点，或点击状态栏，然后重启 IDE。
1. 选择Restart Studio IDE。
2. 回到IDE文件浏览器，删除存在的以下文件或目录：
  - target, dbt_modules, dbt_packages, logs
3. 保存，然后Commit and sync。
4. 再次重启Studio IDE。
5. 在Version Control菜单创建PR，以集成修改。
6. 在Git提供商页面合并PR。
7. 切换到主分支，点击Pull from remote拉取修改。确认.gitignore列出的文件或目录以斜体显示，即可核验。
main 分支上的 dbt 项目，已正确配置 gitignore 文件夹（以斜体突出显示）。

更多操作指导参见详细视频。
任务失败并提示 This run exceeded your account’s run memory limits

失败作业提示This run exceeded your account's run memory limits，表示超过账户运行内存限制。原文说明所有dbt账户的pod内存为600MiB，限制按单次运行计算。内存通常受dbt读取与处理的结果数据量影响；这类数据一般不大，但项目设计可能使其意外膨胀。

常见原因

内存占用较高的常见原因包括：
- dbt run/build：宏通过run query捕获过大的结果集，其中部分数据可能并不需要，导致内存利用低效。
- dbt docs generate：source或模型schema包含大量表，即使不全被dbt使用，也会使目录查询读取很大的结果集。
解决方法

原因通常是向dbt返回了过多数据，例如run_query()或类似宏，或数据库/schema中包含大量非dbt表、视图。可通过group、where或limit重构run_query()中的SQL，减少返回行数；也可改用非dbt表、视图较少的数据库或schema。

视频示例

补充视频展示了如何减少返回行数并重构示例代码。

如果按上述建议处理后仍因账户内存限制导致作业失败，可联系支持团队。

补充资源
- 关于如何节省90分钟的博客文章。
为什么依赖包会出现 Runtime Error？

packages.yml出现以下运行时错误，可能是旧版dbt_utils与当前dbt版本不兼容。
```
Running with dbt=xxx
Runtime Error
  Failed to read package: Runtime Error
    Invalid config version: 1, expected 2  
  Error encountered in dbt_utils/dbt_project.yml
```
报告代码问题

尝试把packages.yml中的旧版dbt_utils更新为dbt Hub列出的最新版本：
```
packages:
- package: dbt-labs/dbt_utils

version: xxx
```
报告代码问题

如果仍存在问题，请联系support@getdbt.com。
错误：找不到 my_project 包

项目级dispatch配置的search_order包含某个包时，dbt预期该包包含可参与分派的宏。如果包中没有任何宏，就会报类似错误：
```
Compilation Error
  In dispatch: Could not find package 'my_project'
```
报告代码问题

这并不表示包或根项目缺失，而是其中没有可用宏，因此它不在dispatch可搜索的范围中。

如果仍存在问题，请联系support@getdbt.com。

查询 SQL 有误或出现数据库错误时会怎样？

SQL存在错误时，dbt会返回数据库给出的错误消息。

$ dbt run --select customers
Running with dbt=1.9.0
Found 3 models, 9 tests, 0 snapshots, 0 analyses, 133 macros, 0 operations, 0 seed files, 0 sources

14:04:12 | Concurrency: 1 threads (target='dev')
14:04:12 |
14:04:12 | 1 of 1 START view model dbt_alice.customers.......................... [RUN]
14:04:13 | 1 of 1 ERROR creating view model dbt_alice.customers................. [ERROR in 0.81s]
14:04:13 |
14:04:13 | Finished running 1 view model in 1.68s.

Completed with 1 error and 0 warnings:

Database Error in model customers (models/customers.sql)
  Syntax error: Expected ")" but got identifier `your-info-12345` at [13:15]
  compiled SQL at target/run/jaffle_shop/customers.sql

Done. PASS=0 WARN=0 ERROR=1 SKIP=0 TOTAL=1

报告代码问题

该模型的所有下游模型也会被跳过。结合错误消息与编译后的SQL进行排查。