# Troubleshooting and limitations - Docs

**The semantic layer is in alpha**

The semantic layer is in alpha, enabled per organization for a small group of customers. There's no dedicated UI yet – you work with it through MCP tools and SQL. Tool names and behavior may change between releases. Found a bug, or want access? [Contact support](https://app.posthog.com/home#supportModal) and mention the semantic layer alpha.

## Have a question? Ask PostHog AI

Ask PostHog AI

## I don't see the semantic layer tools in my MCP client

The alpha is enabled per organization. If the `data-catalog-*` tools are missing:

1.  Confirm your organization is in the alpha – [contact support](https://app.posthog.com/home#supportModal) to request access.
2.  Reconnect or restart your MCP client after enablement; clients cache the tool list.
3.  Check your API key has the `data_catalog` scope.

Similarly, if `system.information_schema.metrics` raises "Unknown table", the alpha isn't enabled for your organization yet.

## My agent can't approve a metric

Three causes, in order of likelihood:

1.  **Missing scope.** Approval needs `data_catalog_approval` on the API key – `data_catalog` alone can propose but never promote. This split is deliberate; see [governance](/docs/semantic-layer/governance.md#api-scopes).
2.  **The metric is drifted.** Approval is blocked while `is_drifted` is true. Resolve the drift first (below), then approve.
3.  **You didn't type "confirm".** Approval only executes after you reply with the literal word "confirm". The agent can't do it for you – that's the point.

## Why is my metric drifted?

The metric was created from an insight, and that insight's query has changed since the snapshot (or the insight was deleted). To resolve:

-   **Keep the new definition:** update the metric to re-snapshot the insight's current query, then re-approve.
-   **Keep the old definition:** unlink the metric from the insight (set `source_insight_short_id` to null) so it stands on its own definition, then re-approve.

Compare the metric's `compiled_query` (from a run) with the insight's current query to see what changed. Until it's re-approved, results are labeled noncanonical.

## I deleted a metric but can't reuse the name

By design. Names are write-once and stay reserved after deletion, so a stored reference to a name can never silently point at a different definition. Pick a new name.

## An agent keeps proposing a join we don't want

Reject the proposal with `data-catalog-relationship-reject`. Rejection persists forever and the pair is never re-proposed – in either direction.

The flip side: **rejection has no undo** in the alpha. If you rejected a proposal by mistake and need the join anyway, create it directly as a [data warehouse join](/docs/data-warehouse/join.md) – the catalog's rejection only suppresses re-proposals, not manual joins.

## Where's the UI?

There isn't one yet. During the alpha the semantic layer is MCP tools and SQL only – no catalog page in the app. Also worth knowing:

-   Tool names and behavior may change between releases
-   The alpha is enabled per organization, not per user or project
-   `last_run_at` is updated at most every 30 minutes, so treat it as approximate

Feedback on any of this shapes what the beta looks like – [tell us what's missing](https://app.posthog.com/home#supportModal).

### Community questions

Ask a question

### Was this page useful?

HelpfulCould be better