Перейти к основному содержимому

Отладка ошибок

Устранение неполадок
Платформа dbt
Начальный уровень
Menu

    Общий процесс отладки​

    Умение отлаживать код — это навык, который поможет вам стать отличным специалистом!

    1. Прочитайте сообщение об ошибке — при разработке dbt мы стараемся сделать сообщения об ошибках как можно более полезными. Сообщение об ошибке, которое выдает dbt, обычно содержит тип ошибки (подробнее о типах ошибок ниже) и имя файла, в котором она возникла.
    2. Изучите файл, вызвавший проблему, и посмотрите, нет ли очевидного способа ее исправить.
    3. Изолируйте проблему — например, запускайте по одной модели за раз или отмените изменения в коде, которые привели к сбою.
    4. Освойте работу со скомпилированными файлами и логами.
      • Каталог target/compiled содержит операторы select, которые можно выполнить в любом редакторе запросов.
      • Каталог target/run содержит SQL-код, который dbt выполняет для построения ваших моделей.
      • Файл logs/dbt.log содержит все запросы, которые выполняет dbt, и дополнительные записи логов. Последние ошибки находятся в конце файла.
      • Пользователи dbt: используйте перечисленные выше файлы и каталоги или вкладку Details в выводе команды.
      • Пользователи dbt v1: обратите внимание, что ваш редактор кода может скрывать эти файлы в дереве представление Справка по VSCode).
    5. Если вы никак не можете решить проблему, попробуйте обратиться за помощью. Прежде чем это сделать, уделите время грамотной формулировке вопроса, чтобы другие могли быстро разобраться в проблеме.

    Типы ошибок​

    Ниже мы перечислили некоторые из наиболее распространенных ошибок. Полезно понимать, что именно 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 (обратите внимание на множественное число):
    dbt_project.yml
    profile: jaffle_shops # обратите внимание на множественное число
    • Проверьте профили, которые у вас есть в файле profiles.yml. Например, этот профиль называется jaffle_shop (обратите внимание на единственное число).
    profiles.yml
    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")
    dbt_project.yml
    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-коде вашей модели. Чтобы исправить её:

    1. Откройте файл с ошибкой:
      • dbt: Откройте модель (в данном случае models/customers.sql, как указано в сообщении об ошибке)
      • dbt v1: Откройте модель, как описано выше. Также откройте скомпилированный SQL (в данном случае target/run/jaffle_shop/models/customers.sql, как указано в сообщении об ошибке) — может быть полезно расположить эти файлы рядом в редакторе кода.
    2. Попробуйте повторно выполнить SQL, чтобы локализовать ошибку:
      • dbt: Используйте кнопку Preview в файле модели
      • dbt v1: Скопируйте и вставьте скомпилированный запрос в инструмент для выполнения запросов (например, веб-интерфейс Snowflake или настольное приложение, такое как DataGrip / TablePlus) и выполните его
    3. Исправьте ошибку.
    4. Повторно запустите модель, выполнение которой завершилось с ошибкой.

    Иногда причиной становятся служебные запросы, которые 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-запросе ошибка или я получу ошибку базы данных?

    Нашли ошибку?

    0