Skip to main content
Use this page when an assistant connected to Codemod MCP can’t read a dashboard, preview a widget, or save your changes. For sign-in, scopes, and approval prompts, see MCP troubleshooting.

​
Before you start

Check these first:
  • You connected with OAuth (the browser sign-in) and approved insights:read. To create or change dashboards, you also approved insights:write.
  • You’re signed in to the organization that owns the repositories the dashboard uses.
  • The assistant previews each widget before it saves the dashboard.

​
Authentication and access

Codemod API keys work only with the Grep read tools. If a tool call returns This API key can only call Grep read tools, remove the API key from your client configuration and connect with OAuth instead. See Connect your client.
The server doesn’t recognize the key. Check that you copied the whole key, or create a new one in the Codemod app. If you need Insights tools, connect with OAuth instead.
The assistant acts in the organization you were signed into when you approved the connection. Sign in to that organization in the browser, then reconnect the server. You also need access to every repository a dashboard references. See Insights access.
Confirm that the repository is connected and that your git account or organization can access it. For repository groups, confirm that the group belongs to your active organization. The error might not say which repository caused the problem, so test repositories separately in previews. Only save a narrower dashboard if you intend to change its scope.

​
Widget and query input

Ask the assistant to read the widget format again and fix the fields it reports. Common causes are a misspelled query source, a metric name that the package doesn’t emit, or a formula that references a query letter that doesn’t exist.
Insights runs one workflow step at a time. Insights can show a warning for a package if the metric is defined in an imported file (metric-in-imported-file), outside the workflow steps (metric-outside-workflow-steps), or depends on files written by another step (step-depends-on-other-step-files). Update the package so the selected step emits the metric itself, then publish a new version. See Metrics in Insights.

​
Preview, save, and freshness

Preview each query-backed widget before you save, so you can see real results and fix errors early.
1

Preview the widget

insights_dashboard_preview_widget waits up to 90 seconds and returns ready, error, or pending. If it returns pending, wait, then ask the assistant to check again. Don’t start a new preview of the same widget.
2

Save the widget as previewed

Ask the assistant to save the widget exactly as you previewed it. If it changes the code or query names, preview it again before saving.
3

Check the saved dashboard

Ask the assistant to read the dashboard with insights_dashboard_get and check each widget’s status.
If an update returns CONFLICT, someone changed the dashboard after the assistant read it. Ask the assistant to read the dashboard again and reapply your change.