Отладка ошибок
Общий процесс отладки
Умение отлаживать код — это навык, который поможет вам стать отличным специалистом!
- Прочитайте сообщение об ошибке — при разработке dbt мы стараемся сделать сообщения об ошибках как можно более полезными. Сообщение об ошибке, которое выдает dbt, обычно содержит тип ошибки (подробнее о типах ошибок ниже) и имя файла, в котором она возникла.
- Изучите файл, вызвавший проблему, и посмотрите, нет ли очевидного способа ее исправить.
- Изолируйте проблему — например, запускайте по одной модели за раз или отмените изменения в коде, которые привели к сбою.
- Освойте работу со скомпилированными файлами и логами.
- Каталог
target/compiledсодержит операторыselect, которые можно выполнить в любом редакторе запросов. - Каталог
target/runсодержит SQL-код, который dbt выполняет для построения ваших моделей. - Файл
logs/dbt.logсодержит все запросы, которые выполняет dbt, и дополнительные записи логов. Последние ошибки находятся в конце файла. - Пользователи dbt: используйте перечисленные выше файлы и каталоги или вкладку
Detailsв выводе команды. - Пользователи dbt v1: обратите внимание, что ваш редактор кода может скрывать эти файлы в дереве представление Справка по VSCode).
- Каталог
- Если вы никак не можете решить проблему, попробуйте обратиться за помощью. Прежде чем это сделать, уделите время грамотной формулировке вопроса, чтобы другие могли быстро разобраться в проблеме.
Типы ошибок
Ниже мы перечислили некоторые из наиболее распространенных ошибок. Полезно понимать, что именно dbt делает «за кулисами», когда вы выполняете команду вроде dbt run.
| Этап | Описание | Тип ошибки |
|---|---|---|
| Инициализация | Проверьте, что это проект dbt, и что dbt может подключиться к хранилищу данных | Runtime Error |
| Парсинг | Проверьте, что фрагменты Jinja в файлах .sql и файлы .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, чтобы перечислить файлы в директории, или также открыть директорию в редакторе кода и увидеть файлы в "дереве".
Не удалось найти профиль
Running with dbt=1.7.1
Encountered an error:
Runtime Error
Could not run dbt
Could not find profile named 'jaffle_shops'
Отладка
- Проверьте ключ
profile:в вашемdbt_project.yml. Например, этот проект использует профильjaffle_shops(обратите внимание на множественное число):
profile: jaffle_shops # обратите внимание на множественное число
- Проверьте профили, которые у вас есть в файле
profiles.yml. Например, этот профиль называетсяjaffle_shop(обратите внимание на единственное число).
jaffle_shop: # это не соответствует ключу profile:
target: dev
outputs:
dev:
type: postgres
schema: dbt_alice
... # другие детали подключения
- Обновите их так, чтобы они совпадали.
- Если вы не можете найти свой файл
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, как указано в "'hello' was unexpected")
name: jaffle_shop
hello: world # это не разрешено
- Используйте справочный раздел для файлов
dbt_project.yml, чтобы исправить эту проблему. - Если вы используете ключ, который является допустимым согласно документации, проверьте, что вы используете последнюю версию dbt с помощью
dbt --version.
Ошибки компиляции
Примечание: если вы используете Studio IDE для работы над проектом dbt, эта ошибка часто отображается в виде красной полосы в командной строке во время работы над проектом. Для пользователей dbt v1 такие ошибки обнаруживаются только при выполнении dbt run или 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, чтобы передать ошибку, а затем просто передаем ее вам.
Этот конкретный пример связан с забытым тегом {% endmacro %}, но вы также можете получить такие ошибки за:
- Забытую закрывающую
} - Закрытие цикла
forперед закрытием оператораif
Чтобы исправить это:
- Перейдите к ошибочному файлу (например,
macros/cents_to_dollars.sql), указанному в сообщении об ошибке - Используйте сообщение об ошибке, чтобы найти свою ошибку
Чтобы этого избежать:
- (dbt v1 only) Используйте сниппеты для автодополнения фрагментов 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: # этот отступ слишком большой!
- name: customer_id
data_tests:
- unique
- not_null
Чтобы исправить это:
- Откройте ошибочный файл (например,
schema.yml) - Проверьте строку в сообщении об ошибке (например,
line 5) - Найдите ошибку и исправьте ее
Чтобы предотвратить это:
- (dbt v1 users) Включите направляющие отступов в вашем редакторе кода, чтобы было проще проверять структуру файлов
- Используйте валидатор YAML (пример) для отладки любых проблем
Неправильная спецификация 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, как указано в "'hello' was unexpected") - Исправьте это. Используйте документы свойств модели, чтобы найти допустимые ключи
- Если вы используете допустимый ключ, проверьте, что вы используете последнюю версию dbt с помощью
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
Ваш DAG в dbt не является ациклическим, и его необходимо исправить!
- Обновите вызовы функции
ref, чтобы разорвать цикл. - Если вам нужно сослаться на текущую модель, используйте переменную
{{ this }}вместо этого.
Ошибки базы данных
Самые сложные ошибки из всех! Эти ошибки исходят из вашего data warehouse, и 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, как указано в сообщении об ошибке) — может быть полезно расположить эти файлы рядом в редакторе кода.
- dbt: Откройте модель (в данном случае
- Попробуйте повторно выполнить SQL, чтобы локализовать ошибку:
- dbt: Используйте кнопку
Previewв файле модели - dbt v1: Скопируйте и вставьте скомпилированный запрос в инструмент для выполнения запросов (например, веб-интерфейс Snowflake или настольное приложение, такое как DataGrip / TablePlus) и выполните его
- dbt: Используйте кнопку
- Исправьте ошибку.
- Повторно запустите модель, выполнение которой завершилось с ошибкой.
Иногда причиной становятся служебные запросы, которые dbt выполняет автоматически:
- Запросы списка объектов в базе данных.
- Запросы на создание схем.
- Хуки
pre-hook,post-hook,on-run-endиon-run-start. - Операции слияния, обновления и вставки для инкрементальных моделей и снимков.
В таких случаях следует проверить журналы — в них содержатся все запросы, выполненные dbt.
- dbt: Чтобы просмотреть журналы, откройте
Detailsв выводе команды или проверьте файлlogs/dbt.log - dbt v1: Откройте файл
logs/dbt.log.
Если вы сталкиваетесь с странной Database Error, может быть хорошей идеей очистить ваши журналы, открыв файл и удалив содержимое. Затем повторно выполните dbt run только для проблемной модели. Журналы будут содержать только нужный вам вывод.
Распространённые ошибки
Preview и dbt run: в чём разница
(Только для пользователей Studio IDE)
- Preview выполняет SQL из активной вкладки. Это аналог запуска скомпилированного
selectизtarget/compiledв редакторе запросов. - dbt run создаёт объекты в базе данных.
Использование кнопки Preview полезно при разработке моделей, когда вы хотите визуально проверить результаты запроса. Однако вам нужно убедиться, что вы выполнили dbt run для всех вышестоящих моделей — в противном случае dbt попытается выбрать from таблицы и представления, которые не были построены.
Забыли сохранить файлы перед запуском
С этим сталкивались все. dbt использует последнюю сохранённую версию файла при выполнении команды. В большинстве редакторов кода, а также в , точка рядом с именем файла означает, что в нём есть несохранённые изменения. Перед запуском любых команд dbt убедитесь, что вы нажали cmd + s (или аналогичную комбинацию) — со временем это становится привычкой.
Редактирование скомпилированных файлов
(Прежде всего для пользователей dbt v1.)
Если вы открыли SQL-файл из каталога target/ для отладки, легко случайно внести правку в скомпилированный файл. Настройте редактор так, чтобы файлы в target/ отображались серым. Так проще отличить их от исходных файлов модели.
Часто задаваемые вопросы
Вот некоторые полезные часто задаваемые вопросы, которые помогут вам отладить ваш проект dbt:
-
Как создать HAR файлы
-
Повторное подключение к Snowflake через OAuth после истечения срока действия аутентификации
-
Почему задание dbt выдаёт ошибку «Could not parse dbt_project.yml»?
-
Как исправить мой файл .gitignore?
-
Я получаю ошибку 'Этот запуск превысил лимиты памяти вашего аккаунта' в моей неудавшейся задаче
-
Почему я получаю ошибку времени выполнения в моих пакетах?
-
[Ошибка] Не удалось найти пакет my_project
-
Что произойдет, если в моем SQL-запросе ошибка или я получу ошибку базы данных?

