---
title: Troubleshoot app connections
description: Diagnose loading, credentials, authorization, review, reconnect, and disconnect problems in Apps.
---

Use this guide when an app does not load, connect, reconnect, save its tool access, or
disconnect as expected. Start from the state Runner actually shows rather than repeating a
provider flow blindly.

**Entry path:** **Project → Apps**

## Before you start

1. Confirm that you opened Apps for the intended project and workspace.
2. Clear **Search apps** and any Agent Apps category filter.
3. Refresh the page once and wait for connection states to load.
4. Read the exact card state: **Connect**, **Connecting...**, **Connected**, **Reconnect**,
   **Pending review**, or an action-required notice.
5. Open only the recovery action that matches that state.
6. Never include an API key, secret, identity document, payment detail, or full provider
   callback URL in a support message or screenshot.

## Important controls and results

| Control | What happens after you select it |
| --- | --- |
| **Clear search** | Removes the current Agent Apps search so the available catalog can appear again. |
| **Connect** / **Connect & Authorize** | Opens the setup or external authorization flow for that app. |
| **Reconnect**, when shown | Restarts authorization for an existing provider connection. |
| **Retry** | Repeats the failed catalog, tool-list, or connection request shown by the current panel. |
| **Continue Onboarding** | Returns to the existing Stripe onboarding flow when action is required. |
| **Disconnect** | Opens a confirmation or starts the documented removal flow; verify the saved state before changing provider-side credentials. |

## Symptom and recovery table

| What you see | Likely meaning | Safe next action |
| --- | --- | --- |
| App is missing | Search, a category, workspace access, or a conditional feature is hiding it. | Clear search, choose **All**, then confirm the feature is available for this workspace. |
| Card keeps loading | Runner has not resolved the saved connection. | Refresh Apps once. Avoid submitting another connection while the state is unknown. |
| **No apps found** | No Agent App matches the current filters. | Select **Clear search**. |
| **Connect** does nothing | A required field is empty or invalid, or the provider flow could not start. | Read field errors, re-copy the required value, and allow provider popups when applicable. |
| **Connecting...** does not finish | The external authorization was closed, blocked, or never returned a result. | Return to Apps, refresh the state, then use **Reconnect** if Runner offers it. |
| Provider says success but Runner does not | Runner has not confirmed a usable connection. | Re-open Apps. Treat only **Connected** as success; use **Reconnect** instead of creating duplicates. |
| **Reconnect** | Existing authorization needs attention. | Select it and complete the provider flow again. |
| **Pending review** | Stripe is reviewing submitted details. | Follow action notices; do not start another account merely to remove the label. |
| **Stripe actions required** | Stripe needs information or has paused a capability. | Review **Due now**, **Due later**, **In review**, payment, and payout notices, then use **Continue Onboarding** when shown. |
| API key or secret rejected | The value is wrong, expired, from the wrong account, or not accepted for this integration. | Re-copy it from the provider. Do not edit secrets by guesswork. |
| Shopify domain invalid | The value is not the permanent Shopify store domain. | Use `your-store.myshopify.com`, not a custom storefront domain. |
| Agent App authorization window is blocked | The browser prevented the external flow. | Allow popups for Runner and start **Connect & Authorize** again. |
| Agent App tools fail to load | Runner could not retrieve that app's tool list. | Select **Retry** in **App details**. |
| Tool switch reports failure | The new tool setting was not saved. | Wait for the switch to refresh, confirm its current state, then retry once. |
| Disconnect reports failure | Runner did not confirm removal. | Assume the existing connection is still active and re-open Apps before trying again. |

## Provider-specific checks

### Stripe

- Continue an existing onboarding attempt with **Reconnect** or **Continue Onboarding**.
- Read action requirements instead of relying only on the card color.
- A published storefront can still have payments paused or unavailable.
- Use the Stripe dashboard action only after Runner has an associated account.

### Email

- A failed switch change returns to the saved state.
- An enabled switch does not prove that a particular email was delivered.
- Verify the store event, recipient, email configuration, and currently published version
  with safe test data.

### Shippo

- Re-copy the Shippo API key from the intended account.
- A connected card does not verify rates, carriers, labels, or shipment creation.

### Shopify

- Use the permanent `myshopify.com` domain.
- If a workspace already has a store connected, review it before disconnecting.
- Restart authorization when the connection link expires or the returned store does not
  match the domain you entered.

### CJ Dropshipping

- Confirm the API key belongs to the CJ account you intend to use.
- After disconnecting, Runner falls back to the shared CJ account, so verify the account
  context before future supplier actions.

### 4PX

- Confirm the API key and secret belong to the same account and are in the correct fields.
- A connected card does not prove that a destination or order is eligible for fulfillment.

### Agent Apps

- The entire section or an individual app can be conditionally unavailable.
- Clear filters before treating an app as absent.
- Review tool switches before reconnecting; do not grant more access merely to make setup
  easier.

## Disconnect failed or produced an uncertain result

1. Keep the provider account and current store operations unchanged.
2. Re-open **Project → Apps** and check the card state.
3. If it still shows connected, treat the connection as active.
4. Do not delete provider-side credentials until you understand whether active checkout,
   email, shipping, supplier, or fulfillment work still depends on them.
5. Retry the Runner disconnect only after the state is clear.

## Ask for help safely

Provide:

- the app name;
- the exact visible state and error text;
- whether the issue occurs while connecting, returning, managing tools, or disconnecting;
- the project URL without secret query values; and
- a privacy-safe screenshot if it materially shows the problem.

Do not provide the actual API key, secret, provider password, identity document, payment
details, customer data, or hidden authorization parameters.

## Related guides

- [Apps and integrations overview](../apps-and-integrations)
- [Connect, manage, and reconnect an app](./connect-manage-reconnect)
- [Connect and control Agent Apps](./agent-apps)