Troubleshooting and limitations

Have a question? 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 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.
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 – 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.