Troubleshoot app connections

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

Confirm that you opened Apps for the intended project and workspace.
Clear Search apps and any Agent Apps category filter.
Refresh the page once and wait for connection states to load.
Read the exact card state: Connect, Connecting..., Connected, Reconnect, Pending review, or an action-required notice.
Open only the recovery action that matches that state.
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

Keep the provider account and current store operations unchanged.
Re-open Project → Apps and check the card state.
If it still shows connected, treat the connection as active.
Do not delete provider-side credentials until you understand whether active checkout, email, shipping, supplier, or fulfillment work still depends on them.
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.

Troubleshoot app connections

On This Page