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.

​
Requirements

To follow the steps in this guide, you’ll need:
  • An Omni connection with a configured dbt integration
  • Querier, Modeler, or Connection Admin permissions to access the model. To ignore issues, Modeler or Connection Admin permissions are required.

​
About dbt sync issues

Issues never block a sync. Omni imports everything it can translate and records the rest, so a warning on one metric doesn’t stop the models around it from importing. An issue persists until you fix the underlying problem in dbt and re-sync, or ignore it. When a sync identifies an issue, the icon in the model IDE will display an indicator:

The dbt icon in the model IDE with an issue indicator

When there are issues, clicking the icon will clear the indicator and open the Sync page. The top of the page displays a summary of the most recent sync and a summary of any issues found:

Issue summary on the Sync page

The summary breaks the issues out by level: Along with the Sync page summary, Omni flags files and directories containing issues in the file list. See Troubleshooting dbt sync issues for more information. Refer to the dbt sync issue reference for potential issues and how to resolve them.

​
Troubleshooting dbt sync issues

The dbt IDE is read-only, so resolving an issue is a round trip: diagnose it in Omni, fix it in your dbt project, then re-sync in Omni. To edit dbt models from Omni rather than in your project, see Working with dbt models.
1

Open the flagged file

  1. In Omni, open the model IDE and click the dbt icon in the left navigation.
  2. In the file list, locate a file with an issue indicator. Each flagged file displays an icon and count for every issue type it contains, and collapsed directories roll up the counts of everything inside them, so you can find affected files without expanding the whole tree.

    Files with issues will have indicators next to their names in the file list

  3. Click the file to open it.
2

Review the issue

The file’s issues are listed in the dbt sync issues panel below the editor:

The dbt sync issues panel lists each issue affecting the current file

Click an issue to jump to the line that caused it or Troubleshoot for details. Alternatively, you can click Ignore to suppress it.
Issues in dbt model files only display in the dbt sync issues panel. This is because dbt models are reported against .sql files, which don’t have lines to resolve.
3

Fix the issue in dbt

Make the correction in your dbt project and push it.
4

Re-sync Omni

In Omni, click Sync now on the Sync page to pick up the change. Resolved issues will be removed on the next sync.

​
Ignoring dbt sync issues

Modeler or Connection Admin permissions are required to ignore issues, as ignoring an issue edits the model.
Some issues aren’t worth acting on, such as an unsupported feature you don’t plan to remove or duplicate measures you’ve already hidden. Ignoring an issue suppresses the notifications and indicators in the dbt IDE, but it doesn’t fix the underlying issue. You can ignore:
  • One issue in a file by clicking Ignore on the issue in the dbt sync issues panel.
  • All issues in a file by right-clicking on the file in the file list and selecting Ignore all issues in this file.
  • All issues in a directory by right-clicking on the directory in the file list and selecting Ignore all issues in this directory. Suppression will be applied to every file and subdirectory inside it.

​
dbt sync issue reference

  • What it means - Your dbt metric definitions produced more than one copy of the same measure.
  • How to fix it - Hide all but one of the duplicate measures within the view, then ignore the issue.
  • What it means - Omni doesn’t support this dbt feature yet, so the entity was skipped during generation.
  • How to fix it - Remove or rework the use of the feature in your dbt project.
  • What it means - The metric depends on itself through a chain of other metrics, so it can’t be resolved.
  • How to fix it - In your dbt project, trace the metrics it references and remove or redefine one of the dependencies.
  • What it means - The entity references something Omni couldn’t find.
  • How to fix it - Check that the dependency exists and is spelled correctly, and that the file defining it is part of the dbt project.
  • What it means - The entity depends on something that itself failed to translate.
  • How to fix it - Fix the issue reported on the dependency first. This issue should clear once the issue on the dependency is resolved.
  • What it means - The derived metric references aliases that aren’t defined.
  • How to fix it - Add the missing inputs to the metric, or correct the alias names so they match its declared inputs.
  • What it means - The dimension has the same name as a column already present in the warehouse table.
  • How to fix it - Rename the dimension so it no longer collides with the underlying column.
  • What it means - Omni couldn’t parse the SQL for this entity.
  • How to fix it - Look for dialect-specific syntax or constructs Omni doesn’t understand, simplify the expression, and re-sync.
  • What it means - A Jinja expression couldn’t be rendered.
  • How to fix it - Omni renders only a subset of dbt’s Jinja. Review the reported Jinja and avoid macros and context Omni can’t resolve.
  • What it means - Ratio metrics with filters require simple metric inputs, and one of this metric’s inputs isn’t one.
  • How to fix it - Point the input at a simple metric, or remove the filters from the ratio metric.
  • What it means - Based on your dbt manifest, Omni expected a view built at a specific database, schema, and alias, and couldn’t find it.
  • How to fix it - Follow these steps to identify and resolve the issue:
    1

    Get the database location from the dbt sync issues panel

    In the file in the dbt IDE, click Troubleshoot on the issue in the dbt sync issues panel. The popover contains the name of the database, schema, and table Omni expected based on your dbt manifest, along with the Omni view name it looked for.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.
    2

    Verify visibility in Omni

    • Check UI visibility. Look for the table in the All views and fields section of a workbook. If it’s missing, it hasn’t been ingested into the Omni model layer yet.
    • Try querying the table with SQL. Use its fully qualified name (FQN), for example DATABASE.SCHEMA.TABLE. In a workbook, 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
    3

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

    Check database permissions

    For Omni to pull in dbt schemas, the database user Omni connects with 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, including grants covering your dbt schemas - existing objects and, where supported, future objects so new models are accessible after each build.
    5

    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 schemas.
    • 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.
    6

    Refresh the schema

    If permissions are correct but models are still missing, refresh the schema. You can scope this to your specific dbt 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.
    7

    Check your dbt project's configuration

    Lastly, in your dbt project:
    • Define 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 step 4 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 in the Sync page and the files responsible are flagged in the file list.
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 also won’t raise an issue for being unmatched.
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.