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

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

Назад к гайдам
Troubleshooting
dbt Core
dbt platform
Beginner
Menu

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

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

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

    Типы ошибок​

    Ниже мы перечислили некоторые из наиболее распространенных ошибок. Полезно понимать, что именно dbt делает «за кулисами», когда вы выполняете команду вроде dbt run.

    StepDescriptionError type
    ИнициализацияПроверьте, что это проект dbt, и что dbt может подключиться к хранилищу данныхRuntime Error
    ПарсингПроверьте, что фрагменты Jinja в файлах .sql и файлы .yml валидны.Compilation Error
    Валидация графаСкомпилируйте зависимости в граф. Проверьте, что он ацикличен.Dependency Error
    Выполнение SQLЗапустите моделиDatabase Error
    Loading table...

    Давайте углубимся в некоторые из этих ошибок и как их отлаживать 👇. Примечание: не все ошибки здесь охвачены!

    Ошибки во время выполнения​

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

    В некоторых случаях эти ошибки могут возникать в результате запросов, которые dbt выполняет "за кулисами". К ним относятся:

    • Интроспективные запросы для перечисления объектов в вашей базе данных
    • Запросы на создание схем
    • pre-hooks, post-hooks, on-run-end hooks и on-run-start hooks
    • Для инкрементных моделей и снимков: операторы merge, update и insert

    В таких случаях стоит проверить логи — они содержат все запросы, которые выполнял dbt.

    • dbt: используйте раздел Details в выводе команды, чтобы посмотреть логи, либо проверьте файл logs/dbt.log
    • dbt Core: откройте файл logs/dbt.log.
    Изоляция ошибок в журналах

    Если вы сталкиваетесь с странной Database Error, может быть хорошей идеей очистить ваши журналы, открыв файл и удалив содержимое. Затем повторно выполните dbt run только для проблемной модели. Журналы будут содержать только нужный вам вывод.

    Общие ошибки​

    Preview vs. dbt run​

    (только для пользователей Studio IDE)

    Существует два интерфейса, которые выглядят похоже:

    • Кнопка Preview выполняет любой SQL-запрос, находящийся в активной вкладке. Это эквивалентно извлечению скомпилированного select-запроса из директории target/compiled и выполнению его в редакторе запросов, чтобы увидеть результаты.
    • Команда dbt run создает отношения в вашей базе данных

    Использование кнопки Preview полезно при разработке моделей, когда вы хотите визуально проверить результаты запроса. Однако вам нужно убедиться, что вы выполнили dbt run для всех вышестоящих моделей — в противном случае dbt попытается выбрать from таблицы и представления, которые не были построены.

    Забыл сохранить файлы перед запуском​

    Мы все были там. dbt использует последнюю сохраненную версию файла, когда вы выполняете команду. В большинстве редакторов кода и в IDE dbt Cloud точка рядом с именем файла указывает на то, что файл имеет несохраненные изменения. Убедитесь, что вы нажали cmd + s (или эквивалент), прежде чем выполнять любые команды dbt — со временем это становится мышечной памятью.

    Забыли сохранить файлы перед запуском​

    С этим сталкивались все. dbt использует последнюю сохранённую версию файла при выполнении команды. В большинстве редакторов кода, а также в Studio IDE, точка рядом с именем файла означает, что в нём есть несохранённые изменения. Перед запуском любых команд dbt убедитесь, что вы нажали cmd + s (или аналогичную комбинацию) — со временем это становится привычкой.

    Редактирование скомпилированных файлов​

    (Чаще встречается у пользователей dbt Core)

    Часто задаваемые вопросы​

    Вот некоторые полезные часто задаваемые вопросы, которые помогут вам отладить ваш проект dbt:

    • Как создать HAR файлы
    • Ошибка `authentication has expired` при попытке выполнения запросов в IDE.
    • Receiving a 'Could not parse dbt_project.yml' error in dbt job
    • Как исправить мой файл .gitignore?
    • Я получаю ошибку 'Этот запуск превысил лимиты памяти вашего аккаунта' в моей неудавшейся задаче
    • Почему я получаю ошибку времени выполнения в моих пакетах?
    • [Ошибка] Не удалось найти пакет my_project
    • Что произойдет, если в моем SQL-запросе ошибка или я получу ошибку базы данных?

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

    0