DBT Source.yml添加文档与主键测试时description行报错如何排查

1. YAML 隐性语法问题 #

• 检查空白字符类型：即便肉眼看起来缩进符合要求，也有可能混用了制表符（Tab）和空格，YAML 语法严格禁止二者混用。可以开启编辑器的「显示所有字符」功能，确认所有缩进都为空格。
• 检查特殊字符转义：如果 description 内容包含 :、#、{、}、&、* 等 YAML 保留字符，必须给值包裹引号；如果描述本身包含双引号，要改用单引号包裹，也可以用 > 折叠块语法包裹多段描述内容。
• 检查多行描述格式：多行描述如果没有使用 | 或 > 块标识，换行后内容没有保持统一缩进，也会触发语法报错。

2. 配置文件结构与匹配问题 #

• 检查文件配置：确认配置所在的 YAML 文件存放在项目配置的 model-paths 对应目录下（默认是 models/ 目录），且文件后缀必须为 .yml 或 .yaml，类 Unix 系统下大小写敏感，后缀名大小写错误也会触发识别失败。
• 检查模型名匹配：确认 YAML 中配置的 name 字段值和对应 SQL 模型的文件名完全一致，大小写、拼写错误会导致 dbt 无法关联到对应模型，触发配置字段识别错误。
• 检查版本标识：dbt 1.0 以上版本调整了 schema 配置的版本规则，旧项目升级后如果保留了错误的 version 标识，或者新项目缺失必要的顶层结构，也会导致字段识别异常。

3. 配置冲突问题 #

• 检查重复定义：同一模型或同一字段如果在多个 YAML 文件中重复配置 description，或者同一 YAML 文件内重复定义了同一个模型的配置，会触发字段冲突报错。
• 检查测试配置层级：主键测试如果写在 columns 下的 tests 字段时，确认 tests 的缩进层级正确，没有错位覆盖到 description 字段的结构。
• 检查自定义包冲突：如果项目内安装了自定义 dbt 包或宏，修改了默认的 schema.yml 解析规则，也可能导致标准的 description 字段识别异常，可以临时禁用新增的自定义包后重新执行 dbt compile 验证。

4. 环境与缓存问题 #

• 清理缓存重试：执行 dbt clean 命令删除 target 目录下的所有缓存文件，再重新执行 dbt compile，排除旧缓存文件导致的报错。
• 核对版本兼容性：确认你参考的官方文档对应的 dbt 版本和当前运行环境的 dbt 版本一致，不同版本之间对配置字段的格式要求存在细微差异，可以执行 dbt --version 查看当前版本，核对对应版本的配置要求。

内容的提问来源于stack exchange，提问作者WMM