AI assistant troubleshooting

Use this page when a connected AI assistant cannot reach SourceMedium. For Slack, see AI Analyst troubleshooting. Quote the request_id from the assistant’s error when you open a support request.

Before debugging by hand, ask the assistant “are my connections working?”. That routes to the get_account_health tool, which reports each connection’s status, data freshness, and whether the fix belongs to you, your provider, or SourceMedium.

What you see	What to do
401, invalid access token, or the client asks you to sign in again	Sign in again with your SourceMedium account. Tokens expire and cannot be reused across environments.
403 `ACCESS_DENIED`	Your identity does not have access to the selected organization, the organization is inactive, or identity linking needs review. Confirm that you used the email associated with your SourceMedium membership and selected the right organization. A prior browser sign-in is not required. If access is still denied, send support the `request_id`.
The tool is missing from Connected tools on the AI assistants page	Only a successful authorized request creates the row. Finish sign-in and ask a first question.
Re-adding the same URL keeps the old organization	Sign out of the SourceMedium connection inside the assistant, then sign in again. Removing the server often leaves the old grant in place.

There is no in-app disconnect. Stop a client by signing out of it, or ask an Admin to pause the organization.

Source and query errors

Code	Meaning
`SOURCE_UNAVAILABLE`	That source is not connected to SourceMedium. Connect the store or ad account in your workspace; warehouse tools still work.
`REAUTH_REQUIRED`	Reconnect Shopify or Meta in the workspace.
`SOURCE_REQUIRED`	More than one source matches. Pick a source from the options the tool returned.
`SOURCE_NOT_FOUND`	That source handle is not available to this organization. Call `get_data_context` again.
`INVALID_REQUEST`	The tool was called with arguments it could not accept. Usually the assistant’s mistake, not yours. Ask it to call `get_data_context` and retry.
`QUERY_NOT_READ_ONLY`	The SQL is a write. Use a single `SELECT`.
`QUERY_SCOPE_DENIED`	The SQL left the allowed datasets, or a store-scoped agency grant tried `run_bigquery_sql`. Use `query_metrics`, or stay inside `sm_transformed_v2` / `sm_metadata`.
`QUERY_TOO_EXPENSIVE`	Narrow the date range or aggregate. The billed-bytes cap is 10 GiB.
`QUERY_TIMEOUT`	The query ran longer than 60 seconds. Do not retry the same unbounded query.
`RESULT_TOO_LARGE` or `truncated: true`	Narrow the query. Warehouse results cap at 500 rows.
`RATE_LIMITED`	You have hit your own request allowance. Wait, then retry.
`PROVIDER_RATE_LIMITED`	Shopify or Meta throttled the request. Wait, then retry.
`PROVIDER_PERMISSION_DENIED`	Shopify or Meta refused the request itself. The connected account is missing a permission the query needs. Check what that account can see in the provider.
`PROVIDER_ERROR`	Shopify or Meta failed. Usually transient, so retry once.
`INTERNAL_ERROR`	Retry once. If it persists, send support the `request_id`.

Shopify and Meta

There is no approval step for Shopify or Meta. If the store or ad account is connected in your SourceMedium workspace, the assistant can read it. If a provider tool answers SOURCE_UNAVAILABLE, the source is not connected yet; if it answers REAUTH_REQUIRED, reconnect it. Warehouse questions work either way.

Connect an AI assistant

Connection URL, OAuth, and what the assistant can reach.

MCP tool reference

Which tool the assistant should have used, and what each error means it tried.

Connection statuses

Check Shopify or Meta in the workspace before retrying a live-provider tool.

Getting Started

Slack AI Analyst

Connected Assistants

Agent Skills

Reference

AI assistant troubleshooting

Source and query errors

Shopify and Meta

Connect an AI assistant

MCP tool reference

Connection statuses

​Sign-in and access

​Source and query errors

​Shopify and Meta

​Related

Connect an AI assistant

MCP tool reference

Connection statuses

Sign-in and access

Source and query errors

Shopify and Meta

Related