Skip to main content
Each time Omni syncs your dbt project, it translates your dbt models, semantic models, dimensions, measures, and metrics into your Omni semantic model. Anything Omni can’t translate — a model it can’t match to a view, an unsupported dbt feature, a Jinja expression it can’t render — is recorded as an issue and surfaced in the dbt IDE, next to the file that caused it.

​
Requirements

To follow the steps in this guide, you’ll need:
  • An Omni connection with a configured dbt integration
  • Access to the model the connection belongs to. Ignoring issues additionally requires permissions to edit that model.

​
Where issues appear

1

The dbt icon in the model rail

When there are new issues, the dbt icon in the left rail of the model carries an indicator. Clicking it opens the Sync page rather than the file you last had open.The indicator clears once you visit the Sync page, and returns if a later sync turns up something newer.
2

The Sync page

Sync sits at the top of the dbt IDE’s file list and summarizes the most recent sync — either Your dbt configuration looks good, or Your dbt configuration might have issues with a count per level.
3

The file list

Files with issues are flagged with a count next to their name, colored by the most severe level they contain. Collapsed directories roll up the counts of everything inside them, so you can find the affected files without expanding the whole tree.
4

The file itself

Opening a flagged file lists its issues in the dbt sync issues panel below the editor. Clicking an issue jumps the cursor to the line that caused it.YAML files also get markers in the gutter next to the affected line numbers. Issues on dbt models are reported against .sql files, which have no line to resolve, so those appear in the panel only.
The dbt IDE is read-only — you can’t fix issues in Omni. Make the change in your dbt project, push it, and re-sync. To edit a dbt model from Omni, see Working with dbt models.

​
Issue levels

​
Reviewing and resolving issues

1

Open the dbt IDE

In Omni, open the model and click the dbt icon in the left rail.
2

Review the summary

Click Sync at the top of the file list to see how many issues the last sync found, broken down by level.
3

Open a flagged file

In the file list, click a file with an issue count. Its issues are listed in the dbt sync issues panel below the editor.
4

Read the guidance

Click Troubleshoot on an issue. The popover explains What happened and How to fix it for that specific entity, along with the kind and name of the object involved.
5

Fix it in dbt, then re-sync

Make the correction in your dbt project and push it. Back in Omni, click Sync now on the Sync page to pick up the change. Issues that no longer apply drop off on the next sync.

​
Ignoring issues

Some issues aren’t worth acting on — an unsupported feature you don’t plan to remove, or duplicate measures you’ve already hidden. Ignoring an issue hides it from the file list, the gutter, and the summary counts.
  • One issue — Click Ignore on the issue in the dbt sync issues panel.
  • Everything in a file or folder — Right-click the file or directory in the file list and click Ignore all issues in this file or Ignore all issues in this directory. For a directory, this sweeps every descendant.
Ignoring requires permissions to edit the model. Ignore hides the issue rather than fixing it — if the underlying problem is a model that isn’t matched to a view, that model still won’t be queryable in Omni.

​
Issue reference

​
Models not matched to Omni views

This is the only error-level issue, and the most common one. The Troubleshoot popover names the database, schema, and table Omni expected based on your dbt manifest, along with the Omni view name it looked for. Start there: if that location is wrong, your dbt environment settings don’t match your dbt profile or dbt Cloud environment. If the location is right, the view is missing or invisible to Omni.
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 the dbt environment settings

Compare the database, schema, and alias reported in the Troubleshoot popover against the environment’s configuration in Omni. The Default schema and Target name must match the dbt profile or dbt Cloud environment the models were built with. See Configuring dbt environments for what each setting controls.
3

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.
4

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.
5

Refresh the schema

If permissions are correct but models are still missing, refresh the schema: in the model IDE, click Model > Refresh Schema. You can scope this to your specific dev schema to save time.On a dbt-integrated connection, a schema refresh also re-syncs dbt — pulling the latest Git manifest, recompiling the project, and re-running the checks — so there’s no need to sync separately afterward. If nothing has changed in the warehouse and you only need to pick up dbt metadata, a dbt sync on its own is faster.
6

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. If you’re running partial builds, consider enabling deferral on the environment instead — see Using virtual schemas with partial dbt builds.

​
Common questions

Click the following headings for answers to common questions, including problems that show up in your model rather than as flagged issues in the dbt IDE.
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.
Open the dbt IDE and click Sync at the top of the file list. Any dbt object that isn’t matched to an Omni view is counted there, and the files responsible are flagged in the file list below it.
No. Omni syncs everything it can translate and records the rest as issues, so a warning on one metric doesn’t stop the models around it from importing.
Models materialized as ephemeral are compiled as CTEs and never exist as physical tables, so Omni skips them when matching dbt models to views. They won’t appear in Omni, and they won’t raise an issue for being unmatched either.
This often happens if views are flagged with an ignored: true parameter. Omni’s sync may interpret complex views — especially those with dynamic logic like Jinja loops — as “not in use,” and automatically hide them to keep the model clean.To fix this:
1
Navigate to the model IDE.
2
Toggle the view mode to Model. The dropdown may default to Combined, so be sure to update it if needed.
3
Navigate to the file for the view and check for an ignored: true parameter.
4
Remove the parameter and promote the changes to the shared model.
This typically occurs when a dbt-imported measure shares the same name as an existing dimension in the Omni Semantic Layer.To fix the issue:
1
Rename the measure, changing the label or name to be unique (e.g., total_revenue).
2
Check the sql parameter to ensure it points to the raw database column, not the measure name.
3
Hide the dimension by adding the hidden: true parameter. This will hide the raw column in Omni.