How to fix "metric not found" or "dimension not found" in dbt

Almost every failed Semantic Layer query ends in one of two messages: the metric doesn’t match any known metric, or the group-by doesn’t match any available item. Both come with suggestions, and the suggestions usually contain the fix. When they don’t, the cause is in the project, not in the query.

Copy and paste

dbt sl list metrics                              # is the metric there at all?
dbt sl list dimensions --metrics revenue         # exact names it can be grouped by
dbt sl list dimensions --metrics revenue,signups # names valid for both together

With dbt Core, use mf list and run dbt parse first, so that target/semantic_manifest.json is current.

“does not exactly match any known metrics”

ERROR: Got error(s) during query resolution.
Error #1:
  Message:
    The given input does not exactly match any known metrics.
    Suggestions:
      ['revenue', 'revenue_mtd', 'revenue_qtd', 'revenue_wtd', 'revenue_ytd', 'anna_revenue']
  Query Input:
    revenu

In order of likelihood:

A typo or a different name. The suggestions list the closest metric names. Labels don’t count: queries use name, not label.
The metric isn’t in the manifest. Locally, run dbt parse again: mf reads the last semantic_manifest.json, not your YAML. If mf list metrics still doesn’t show it, the file is outside model-paths, or the YAML is in a place dbt doesn’t read it (a model entry in a second file stops the parse instead).
On dbt platform, it isn’t deployed yet. BI tools and the APIs see the metrics of the last successful run in the Semantic Layer’s environment; see how to fix dbt sl query failing because there is no successful production job.

“does not match any of the available group-by-items”

  Message:
    The given input does not match any of the available group-by-items for
    SimpleMetric('revenue'). Common issues are:
      * Incorrect names.
      * No valid join paths exist from the measure to the group-by-item.
        (fan-out join support is pending).
      * There are multiple matching join paths.
        (disambiguation support is pending).
    Suggestions:
      [
        'order__status',
        'order__is_late',
        'customer',
        ...

The causes, and what the fix looks like:

You wrote	Cause	Use instead
`status`	dimension without its entity	`order__status`
`customer__country_code__region` for `signups`	the path starts from the wrong model	`country_code__region` (signups live on customers)
`order__status` for `signups`	a join from one customer to many orders (fan-out)	a customer-level attribute, built in dbt
`order__status` for `revenue,signups`	valid for one metric, not for both	two queries, or a dimension both can reach
`order__order_date__hour`	a grain finer than the column’s `granularity`	`__day` or coarser
`metric_time__extract_month`	not a supported name in the CLI	a month-number dimension

With several metrics, the error names the metric that can’t use the group-by (SimpleMetric('signups') above), which tells you which half of the query to change.

When the dimension should be reachable

If you expected the join to work:

The entity names must match in both models: customer on orders.customer_id and customer on customers.customer_id. Column names don’t matter; entity names do. See how to define entities.
The direction must be towards a primary or unique entity. Two foreign entities with the same name don’t join.
At most two hops. A dimension three models away is out of reach; denormalise it into a nearer model.
No ambiguity. If two paths lead to the same dimension, MetricFlow refuses rather than guesses.

Other errors with the same look

Offset metrics fail with “group-by-items do not include ‘metric_time’” when the query has no metric_time; see how to compare a metric with the prior year. Warehouse errors such as Table with name countries does not exist! during mf validate-configs mean the YAML is fine but the model hasn’t been built in that environment.

Tested with dbt Core 1.12 and MetricFlow 0.213 on DuckDB.