Skip to main content
The dbt Health Check verifies that the models defined in your dbt project code exist in your warehouse and are accessible by the Omni service account. When your code truth (dbt manifest) and database truth (physical tables and views) are out of sync, Omni cannot accurately query or represent your data.

​
Common questions

Omni needs read access to all databases and schemas used by your dbt project, including development schemas. See your database’s connection setup guide to verify the required permissions. If you’re using dbt, make sure those grants also cover your dbt schemas — and where your database supports it, use future grants so new models are accessible after each build.
The Health Check window includes information about the status of all mapped models in Omni. See Accessing the Health Check for step-by-step instructions.

​
Limitations

Ephemeral models won’t appear in the health check. Models materialized as ephemeral are processed as CTEs and don’t exist as physical tables in your warehouse.

​
Requirements

To use the dbt Health Check, you’ll need:

​
Accessing the health check

You have two options to check the status of your dbt environment: through the model IDE or in the connection’s settings.

​
Option 1: Use the model IDE

1
In Omni, click Develop.
2
Click the model you want to work with.
3
In the footer of the IDE, click the Health link (often accompanied by a status icon) to open the Health Check window.
dbt health check status indicator in the Omni bottom toolbar

​
Option 2: Use the connection’s settings

This option requires Connection Admin permissions.
1
In Omni, click Settings.
2
Click Connections > dbt.
3
Scroll down to environments, click the icon next to the environment, and click Edit.
4
Click Health on the left hand side of the modal to open the Health Check section.

​
Understanding health symbols

The Health Check window uses icons to indicate the mapping status of your models:
SymbolMeaning
Green checkThe model is correctly matched to a view or table in Omni.
Yellow warningThe model exists in dbt code but could not be found in the database schema.
Red errorCritical configuration or permission issues are preventing the check.
dbt health check diagnostic window showing model mapping status

​
Troubleshooting checklist

If you’re only missing ephemeral models, skip these steps. As noted in Limitations, dbt Health Check doesn’t currently display this type of model.
If your dbt models are missing or failing the health check, follow this debugging sequence based on common failure points:
1

Verify visibility in Omni

  • Check UI visibility. Look for the tables in the All views and fields section of a workbook. If they’re missing, they haven’t been ingested into the Omni model layer yet.
  • Try querying the table with SQL, specifically with its fully qualified name (FQN), for example DATABASE.SCHEMA.TABLE. In a workbook query, open the SQL editor and run a query:
    • If the FQN works but the table is missing from the model IDE, it is likely a metadata or permission issue
    • If the FQN fails with "Object does not exist," Omni cannot access the table
2

Check database permissions

For Omni to pull in dbt schemas, the user used to connect the database must have permissions to access and query those schemas. Use the setup guide for your database to verify that the database user has the required permissions. Make sure those grants cover your dbt schemas as well — both existing objects and, where supported, future objects so new models are accessible after each build.
3

Check connection settings

Verify that the following settings are correctly defined for the underlying connection:
  • Included Schemas: Check your model file or connection settings for included_schemas. If you filtered your connection (e.g., included_schemas: [omni_dbt]), Omni will hide all other schemas, including the development ones.
  • Other Databases: Ensure the database containing your dev schema is listed in the Other Databases section of the connection settings. It must be listed here if it differs from the primary connection database.
  • Branch Refresh: If testing in a branch, verify that Branch-based schema refresh is enabled. Updates will not sync to Omni otherwise.
4

Refresh and sync

If permissions are correct but models are still missing:
  1. Refresh the schema. In the model IDE, click Model > Refresh Schema. You can scope this to your specific dev schema to save time.
  2. Rerun dbt Health. In the Health Check window, click Re-run dbt. This pulls the latest Git manifest and recompiles the project.
  3. Sync dbt Metadata. In the model IDE, click Model > Sync dbt Metadata to align your virtual schemas with the latest warehouse state.
5

Check dbt-specific configuration

Lastly, check the following in dbt:
  • Environment Variables. If your project uses variables like DBT_CLOUD_ENVIRONMENT_TYPE to name schemas, ensure these are defined in Omni’s dbt environment settings.
  • Run dbt clone. Running dbt clone helps sync your dev environment with production, but remember that cloned objects still require the permissions mentioned in the previous step if future grants aren’t active.