How to fix dbt sl query failing because there is no successful production job

You defined metrics, mf validate-configs or dbt sl validate passes, and yet dbt sl query, Google Sheets or Tableau fails, or doesn’t see the metric. The usual cause is not the YAML. The hosted Semantic Layer answers from a deployment environment, using the semantic manifest of that environment’s last successful run; if there is no such run, or it doesn’t contain your metrics, there is nothing to query.

Copy and paste

The checklist, in the order that finds the problem fastest:

1. Which environment? Account settings → Projects → your project → Semantic Layer: note the environment the Semantic Layer is configured on. It must be a deployment environment.
2. A successful run there? Orchestration → Runs, filtered on that environment. If no run has succeeded, run the deploy job now.
3. Does the job parse? The job’s commands must include dbt parse or dbt build, which write semantic_manifest.json. On dbt v2, dbt’s documentation also asks for dbt docs generate.
4. Are your metrics in that run? Open the run, Artifacts, and look for your metric names in semantic_manifest.json. A metric that exists only in your branch is not there until it is merged into the environment’s branch and a job runs again.
5. Did the run build the tables? The Semantic Layer queries the tables of that environment. A parse-only job is enough for the definitions, but the models must exist in the environment’s schema, built by this job or another one.

Then query again:

dbt sl list metrics
dbt sl query --metrics revenue --group-by metric_time__month --limit 3

Why validate passes and query fails

dbt sl validate checks the definitions in your local project, including uncommitted changes. Queries are answered by the Semantic Layer service from the deployed manifest. Validation proves the YAML is right; it doesn’t prove that the environment has it.

The deploy job to keep

A job that runs after every merge to the production branch, or on the regular schedule, with:

dbt build

dbt build builds the models, runs the tests and writes the manifest in one go. If another job already builds the models, a short job with dbt parse (plus dbt docs generate on dbt v2) after it is enough to refresh the definitions. Without one of the two, a metric merged today is invisible to BI tools until the next full run.

Other causes that look the same

• The Semantic Layer is not configured for the project: step 1 shows a Configure Semantic Layer button instead of an environment.
• A development environment was expected to answer. The documentation lists querying in development environments as coming soon; until then, only the configured deployment environment is served.
• The token or the credential lacks access. A service token needs Semantic Layer Only and Metadata Only; the Semantic Layer credential needs read access to the schemas of the models.
• An unsupported warehouse. The hosted Semantic Layer supports Snowflake, BigQuery, Databricks, Redshift, Postgres and Trino.

Based on the dbt platform documentation (October 2026).