> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Debugging dbt sync issues

> Find and resolve dbt sync issues using the validation issues surfaced in Omni's dbt IDE.

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](/integrations/dbt/setup)
* Access to the model the connection belongs to. Ignoring issues additionally requires permissions to edit that model.

## Where issues appear

<Steps>
  <Step title="The dbt icon in the model rail" titleSize="h3">
    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.
  </Step>

  <Step title="The Sync page" titleSize="h3">
    **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.
  </Step>

  <Step title="The file list" titleSize="h3">
    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.
  </Step>

  <Step title="The file itself" titleSize="h3">
    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.

    <Note>
      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](/integrations/dbt/models).
    </Note>
  </Step>
</Steps>

## Issue levels

| **Level**                                                                         | **Meaning**                                                                                                                                                                          |
| :-------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <Icon icon="circle-xmark" iconType="solid" color="#cf1717" /> **Error**           | A dbt object wasn't matched to an Omni view. The model exists in your dbt project but Omni can't find the table or view it should have been built as, so it isn't queryable in Omni. |
| <Icon icon="triangle-exclamation" iconType="solid" color="#f5dd42" /> **Warning** | Omni couldn't translate part of your dbt project. The entity is skipped, but everything around it still imports.                                                                     |
| <Icon icon="circle-info" iconType="solid" color="#3b82f6" /> **Note**             | Informational. Worth a look, but nothing is missing or broken.                                                                                                                       |

## Reviewing and resolving issues

<Steps>
  <Step title="Open the dbt IDE">
    In Omni, open the model and click the **dbt** icon in the left rail.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

<Note>
  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.
</Note>

## Issue reference

| **Issue**                                                  | **Level** | **What it means**                                                                                                       | **How to fix**                                                                                                        |
| :--------------------------------------------------------- | :-------- | :---------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------- |
| This dbt model was not matched to an Omni view             | Error     | Based on your dbt manifest, Omni expected a view built at a specific database, schema, and alias, and couldn't find it. | See [Models not matched to Omni views](#models-not-matched) below.                                                    |
| Unsupported feature                                        | Warning   | Omni doesn't support this dbt feature yet, so the entity was skipped during generation.                                 | Remove or rework the use of the feature.                                                                              |
| Circular metric dependency                                 | Warning   | The metric depends on itself through a chain of other metrics, so it can't be resolved.                                 | Trace the metrics it references and break the loop by removing or redefining one of the dependencies.                 |
| Dependency not found                                       | Warning   | The entity references something Omni couldn't find.                                                                     | Check that the dependency exists and is spelled correctly, and that the file defining it is part of this dbt project. |
| Dependency not translated                                  | Warning   | The entity depends on something that itself failed to translate.                                                        | Fix the issue reported on the dependency first — this one should clear once that translates.                          |
| Derived metric unknown aliases                             | Warning   | The derived metric references aliases that aren't defined.                                                              | Add the missing inputs to the metric, or correct the alias names so they match its declared inputs.                   |
| Conflicts with a column in your warehouse of the same name | Warning   | The dimension has the same name as a column already present in the warehouse table.                                     | Rename the dimension so it no longer collides with the underlying column.                                             |
| SQL cannot be parsed                                       | Warning   | Omni couldn't parse the SQL for this entity.                                                                            | Look for dialect-specific syntax or constructs Omni doesn't understand, simplify the expression, and re-sync.         |
| Jinja error                                                | Warning   | A Jinja expression couldn't be rendered. Omni renders only a subset of dbt's Jinja.                                     | Review the reported Jinja and avoid macros and context Omni can't resolve.                                            |
| Ratio metric with filters and non-simple dependency        | Warning   | Ratio metrics with filters require simple metric inputs, and one of this metric's inputs isn't one.                     | Point the input at a simple metric, or remove the filters from the ratio metric.                                      |
| Import resulted in duplicate measures                      | Note      | Your dbt metric definitions produced more than one copy of the same measure.                                            | Hide all but one of the duplicate measures within the view, then ignore the issue.                                    |

<h2 id="models-not-matched">
  Models not matched to Omni views
</h2>

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.

<Steps>
  <Step title="Verify visibility in Omni" titleSize="h3">
    * **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](/analyze-explore/sql) 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
  </Step>

  <Step title="Check the dbt environment settings" titleSize="h3">
    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](/integrations/dbt/environments) for what each setting controls.
  </Step>

  <Step title="Check database permissions" titleSize="h3">
    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](/connect-data/setup/index) 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.
  </Step>

  <Step title="Check connection settings" titleSize="h3">
    Verify that the following settings are correctly defined for the underlying connection:

    * **Included Schemas:** Check your [model file](/modeling/models) or connection settings for [`included_schemas`](/modeling/models/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**](/modeling/develop/schema-refreshes) is enabled. Updates will not sync to Omni otherwise.
  </Step>

  <Step title="Refresh the schema" titleSize="h3">
    If permissions are correct but models are still missing, [refresh the schema](/modeling/develop/schema-refreshes): 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](/integrations/dbt/syncing-dbt#sync-only) is faster.
  </Step>

  <Step title="Check dbt-specific configuration" titleSize="h3">
    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](/integrations/dbt/virtual-schemas#partial-dbt-builds).
  </Step>
</Steps>

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

<AccordionGroup>
  <Accordion title="What permissions does Omni need to access dbt development schemas?">
    Omni needs read access to all databases and schemas used by your dbt project, including development schemas. See your database's [connection setup guide](/connect-data/setup/index) 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.
  </Accordion>

  <Accordion title="How can I see which dbt models are pulled into Omni as schemas?">
    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.
  </Accordion>

  <Accordion title="Do issues block the sync?">
    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.
  </Accordion>

  <Accordion title="Why don't my ephemeral models appear in Omni?">
    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.
  </Accordion>

  <Accordion title="Why are views missing from my model?">
    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:

    <Steps>
      <Step noAnchor>
        Navigate to the model IDE.
      </Step>

      <Step noAnchor>
        Toggle the view mode to **Model**. The dropdown may default to **Combined**, so be sure to update it if needed.
      </Step>

      <Step noAnchor>
        Navigate to the file for the view and check for an `ignored: true` parameter.
      </Step>

      <Step noAnchor>
        Remove the parameter and promote the changes to the shared model.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="What causes 'Circular reference' or duplication errors?">
    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:

    <Steps>
      <Step noAnchor>
        **Rename the measure**, changing the label or name to be unique (e.g., `total_revenue`).
      </Step>

      <Step noAnchor>
        **Check the `sql` parameter** to ensure it points to the raw database column, not the measure name.
      </Step>

      <Step noAnchor>
        **Hide the dimension** by adding the [`hidden: true`](/modeling/dimensions/parameters/hidden) parameter. This will hide the raw column in Omni.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

## Related

* [Set up the dbt integration](/integrations/dbt/setup)
* [Configuring dbt environments](/integrations/dbt/environments)
* [Syncing dbt](/integrations/dbt/syncing-dbt)
* [Work with dbt models in Omni](/integrations/dbt/models)
* [Schema refreshes](/modeling/develop/schema-refreshes)