> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sourcemedium.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AI assistant troubleshooting

> Fix sign-in, access, and query errors when an MCP assistant cannot reach SourceMedium.

Use this page when a connected AI assistant cannot reach SourceMedium. For Slack, see [AI Analyst troubleshooting](/docs/ai-analyst/troubleshooting).

Quote the `request_id` from the assistant's error when you [open a support request](/docs/product-tours/get-support).

## Sign-in and access

| 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`                                                | The selected organization is paused, you are not an accepted member, you have never signed into SourceMedium, or you picked the wrong organization. Sign in to the workspace in the browser first, then reconnect. |
| The assistant is missing from **Your connected assistants**        | 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`                    | Shopify or Meta is not enabled for this organization, or that source is not connected. Warehouse tools still work.                                                   |
| `REAUTH_REQUIRED`                       | Reconnect Shopify or Meta in the [workspace](/docs/product-tours/reconnect-data-source).                                                                                  |
| `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.                                                                                                                 |
| `PROVIDER_RATE_LIMITED`                 | 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

Warehouse access does not require an extra review. Shopify and Meta do.

If Settings says those sources need a review, warehouse questions still work. After SourceMedium enables a provider, reconnect the store or ad account if the tool returns `REAUTH_REQUIRED`.

## Related

<CardGroup cols={2}>
  <Card title="Connect an AI assistant" icon="plug" href="/docs/ai-analyst/connect-from-chatgpt-claude">
    Connection URL, OAuth, and what the assistant can reach.
  </Card>

  <Card title="What the MCP tools do" icon="screwdriver-wrench" href="/docs/ai-analyst/mcp-tools">
    Which tool the assistant should have used, and what each error means it tried.
  </Card>

  <Card title="Connection statuses" icon="heart-pulse" href="/docs/product-tours/connection-statuses">
    Check Shopify or Meta in the workspace before retrying a live-provider tool.
  </Card>
</CardGroup>
