# Find the cause and try again.

Source: https://adsuperpowers.ai/docs/troubleshooting

Check connections, workspace context, account permissions and incomplete reports in a useful order.

## Start with a small check

Keep the failing request, exact error and approximate time. Open the [dashboard](https://app.adsuperpowers.ai/dashboard), select the intended workspace and check [Integrations](https://app.adsuperpowers.ai/dashboard/integrations). Then ask your assistant:

```text
Show my active Ad Superpowers workspace and role with workspace_info.
List the [platform] accounts I can access. Do not change anything.
```

This separates a connection problem from a particular report query. If tools do not appear at all, start with your [client's setup guide](https://adsuperpowers.ai/docs/setup).

## Common issues

### The assistant cannot see the tools

**Check:** Is the Ad Superpowers plugin or connector enabled in this client and conversation? Did personal authorization complete for the intended workspace? For ChatGPT, check plugin, app and tool access as separate controls. For a custom connection, check the server address `https://mcp.adsuperpowers.ai/v1`. For key-based setup, check your key in the dashboard without pasting it into the conversation.

**Recover:** Follow the relevant [setup guide](https://adsuperpowers.ai/docs/setup).

The tool list your AI assistant sees is unlocked per connected platform and limited by your access. After connecting another platform, update the tools in your client: for the ChatGPT plugin, start a new chat with the plugin enabled; for a ChatGPT custom connection, use Refresh, then start a new chat; in Claude, toggle the Ad Superpowers connector off and on (or restart the app); in Claude Code, Cursor or other MCP clients, reload the MCP server or restart the client. Your data and settings are untouched.

Published ChatGPT plugin updates follow OpenAI's review process; Refresh applies to custom connections. If your workspace blocks a plugin, app or action, ask its administrator to review access. A custom connection does not bypass that policy. A client can expose only a supported subset of tools.

**Expected result:** The assistant can call an available read tool. Refreshing the tool list does not guarantee a refresh of server-side account permissions.

### An expected account is missing

**Check:** Compare the workspace returned by `workspace_info` with the dashboard. Check platform connection health and the account's selection. If you are a member, ask an owner/admin to check the assignment; members can also reach their own selected connections in that workspace.

**Recover:** Reauthorize the AI connector for the intended workspace if it is bound to the wrong one. Select or assign the correct account as appropriate. The original connector owner may need to reconnect the platform or regain permission there.

**Expected result:** The account appears and a small read request succeeds. Assignment changes can remain stale for up to 30 minutes; a new chat is not a guaranteed fix. See the [assignment limitation](https://adsuperpowers.ai/docs/workspaces#assignment-changes).

### The platform says it is not connected

**Check:** Open the platform in Integrations. The platform login may have lost account access, the grant may need renewal, or a required permission may be missing. Ask the assistant to check connection health if the `skill` tool is available.

**Recover:** The person responsible for that connection should reconnect it in the same workspace and grant the required access. Reconnecting only the AI client does not renew a platform login.

**Expected result:** The connection is available in Integrations and a report for a known account succeeds. A general connected label alone does not prove access to every account.

### A report is slow or rate-limited

**Check:** Read the actual error. A platform rate limit differs from a workspace tool-call allowance. Large date ranges, many accounts and detailed breakdowns can require more work.

**Recover:** Respect any retry delay. Try one account, fewer fields and a shorter period. Avoid starting repeated copies of the same report while the first request is still running. For a workspace usage limit, check the subscription and usage instead of repeatedly retrying.

**Expected result:** The smaller read completes, or returns a specific limit that you can address. A timeout during a write is different: inspect the platform and any recorded result before repeating a change that might already have happened.

### Data is missing, old or different from the platform

**Check:** Compare account IDs, date range, timezone, currency, metric definitions, attribution and filters. Ask whether the result came from a cached response and whether any page, source or step failed. Platform reporting delays and Ad Superpowers caching are separate causes.

**Recover:** Try a small report with the same dimensions and dates as the platform view. Ask the assistant to identify missing data rather than interpret an empty result as zero. API response caching varies by endpoint and data period, from one minute to six hours.

**Expected result:** The answer identifies a comparable dataset or explains a remaining mismatch. See [data flow and caching](https://adsuperpowers.ai/docs/data-privacy#cache) for the storage boundary.

### A workflow is missing or only shows instructions

**Check:** In [Library](https://app.adsuperpowers.ai/dashboard/library?type=workflows&scope=system), check the type, content scope, active workspace, publication status and activation. Ask the assistant to list the workflows available to this connection.

**Recover:** Activate the published workflow in the correct context and use the name returned by discovery. Provide its required inputs. If only instructions appear, ask the assistant to execute the read steps and report which steps could not run.

**Expected result:** You receive actual tool results and an analysis, or an explicit list of missing permissions/data. Loading the workflow template alone does not complete the task. See [workflows](https://adsuperpowers.ai/docs/workflows#run-the-workflow).

## Error messages

| Symptom | What to check | Next action |
| --- | --- | --- |
| 401 / unauthorized | Ad Superpowers sign-in or API key | Reauthorize the connector or use your own valid key |
| Permission denied / read-only | Workspace, role, account access and write permission | Ask the owner to review the specific permission; do not substitute an owner key |
| No accounts / account unavailable | Workspace binding, selection, assignments and platform access | Follow the [account checks](https://adsuperpowers.ai/docs/troubleshooting#missing-accounts) |
| `limit_exceeded` | Which allowance the message names | Review workspace usage or the relevant account/content limit |
| 429 / rate limit | Whether the response supplies a retry delay | Wait as directed and narrow the request |
| Invalid fields or parameters | The exact tool's supported input fields | Use the [tool reference](https://adsuperpowers.ai/docs/tools) and try a smaller request |
| Timeout or unknown write result | Whether the platform accepted the action | Inspect the result before repeating the write |

Keep the provider's error message when asking for support. Similar HTTP statuses can have different causes.

## Platform-specific checks

### Meta Ads

Check the intended ad account ID and that the connected Meta login still has access to it. For an upload, use the [media guide](https://adsuperpowers.ai/docs/media-upload) and inspect its status before retrying.

### Google Ads

Confirm the customer ID and its access through the connected Google login. Use [Google Ads reference](https://adsuperpowers.ai/docs/tools/google-ads) for supported query fields and date handling.

### Google Analytics

Confirm the GA4 property and compatible report dimensions/metrics. Reading normal reports does not grant the additional permission needed for [GA4 change history](https://adsuperpowers.ai/docs/change-history#ga4-permission).

### LinkedIn Ads

Check the account and the connected LinkedIn member's permissions. Use the [LinkedIn reference](https://adsuperpowers.ai/docs/tools/linkedin-ads) to distinguish a supported operation from one the provider does not expose.

## Check service availability

Open the [service health endpoint](https://mcp.adsuperpowers.ai/health). A healthy server response checks service availability; it does not prove that your connector, subscription or platform account is authorized.

If the service is unavailable, try again later. If the service is healthy but your own request keeps failing, send the details below to support.

## Get help

Contact [support@adsuperpowers.ai](mailto:support@adsuperpowers.ai) with your AI client, workspace name, platform, account ID if relevant, exact error, approximate time and the small request you tried. Redact passwords, API keys, OAuth tokens, signed upload URLs and confidential report content. Include what you expected and which checks succeeded.

For external Logging that is pending, partial or needs attention, follow the [change-history status guide](https://adsuperpowers.ai/docs/change-history#status-and-recovery).