> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended**:
> ```bash
> npx @scalekit-inc/cli setup
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for 40+ agents.
> Features: full-stack-auth, agent-auth, mcp-auth, modular-sso, modular-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Troubleshoot connection errors

Diagnose connection failures, connected account issues, and tool execution errors in AgentKit.
Use this guide when a connection fails during OAuth, a connected account shows an unexpected status, or a tool call fails. Start with the diagnostics below, then open the matching scenario.

For connection setup errors (redirect URI mismatch, session expiry, token exchange failures), also see [Common scenarios on Configure connections](/agentkit/connections/#common-scenarios).

## Start with diagnostics

Check the connected account status first. That tells you whether the user never finished OAuth, still needs identity verification, tokens expired, or the account is disconnected.

  ### Python

```python
account = scalekit_client.actions.get_connected_account(
    identifier="user_123",
    connection_name="gmail",
)

print(account.status)  # ACTIVE, EXPIRED, PENDING_AUTH, PENDING_VERIFICATION, or DISCONNECTED
print(account.scopes)
```

  ### Node.js

```typescript
const account = await scalekit.actions.getConnectedAccount({
  identifier: 'user_123',
  connectionName: 'gmail',
});

console.log(account.status); // ACTIVE, EXPIRED, PENDING_AUTH, PENDING_VERIFICATION, or DISCONNECTED
console.log(account.scopes);
```

| Status | Meaning |
|--------|---------|
| `ACTIVE` | Credentials are valid; tool calls should work |
| `EXPIRED` | Access token expired and needs refresh or re-authentication |
| `PENDING_AUTH` | User has not finished OAuth, or re-authentication is in progress |
| `PENDING_VERIFICATION` | OAuth succeeded; user identity verification is still required |
| `DISCONNECTED` | Account was manually disconnected |

If status is `ACTIVE` but a tool still fails, run a read-only tool (for example `gmail_get_profile`) to confirm the connection end to end. The error message usually points to scopes, credentials, or provider rate limits.

## Connected account status

## Status is `PENDING_AUTH`

The user has not finished OAuth, or you initiated re-authentication and the user has not completed it yet. Generate an authorization link and send it through your app (email, in-app prompt, or settings page).

  ### Python

```python
if account.status == "PENDING_AUTH":
    link = scalekit_client.actions.get_authorization_link(
        connection_name="gmail",
        identifier="user_123",
    )
    print(link.link)
```

  ### Node.js

```typescript
if (account.status === 'PENDING_AUTH') {
  const link = await scalekit.actions.getAuthorizationLink({
    connectionName: 'gmail',
    identifier: 'user_123',
  });
  console.log(link.link);
}
```

Status changes to `ACTIVE` after the user completes OAuth (or to `PENDING_VERIFICATION` if your connection requires identity verification).

## Status is `PENDING_VERIFICATION`

OAuth succeeded, but Scalekit is waiting for the user to complete identity verification before the account becomes `ACTIVE`. Send the user through your verification flow.

See [Verify user identity](/agentkit/user-verification/) for configuration and API calls. After verification succeeds, status should move to `ACTIVE`.

## Status is `EXPIRED`

The access token expired and Scalekit could not refresh it automatically. Try a manual refresh first. If refresh fails, send the user a new authorization link.

  ### Python

```python
try:
    account = scalekit_client.actions.refresh_connected_account(
        identifier="user_123",
        connection_name="gmail",
    )
    if account.status != "ACTIVE":
        link = scalekit_client.actions.get_authorization_link(
            connection_name="gmail",
            identifier="user_123",
        )
        print(link.link)
except Exception as exc:
    print(exc)
```

  ### Node.js

```typescript
try {
  const refreshed = await scalekit.actions.refreshConnectedAccount({
    identifier: 'user_123',
    connectionName: 'gmail',
  });
  if (refreshed.status !== 'ACTIVE') {
    const link = await scalekit.actions.getAuthorizationLink({
      connectionName: 'gmail',
      identifier: 'user_123',
    });
    console.log(link.link);
  }
} catch (error) {
  console.error(error);
}
```

## Status is `DISCONNECTED`

The connected account was manually disconnected in Scalekit or the user removed your application's access at the provider (for example **Google Account** > **Third-party access**). Re-authentication is the only fix.

Send a new authorization link and explain that the user disconnected the integration. Pending tool executions fail until the user reconnects.

> caution: Handle disconnected accounts in your app
>
> Surface `DISCONNECTED` status in your UI and stop scheduling tool calls for that connected account until the user reconnects.

## OAuth flow errors

## The provider returns an error on the callback URL

Read the `error` and `error_description` query parameters on the callback. Common values:

| Error | Meaning | What to do |
|-------|---------|------------|
| `access_denied` | User cancelled consent | Offer to restart the flow |
| `invalid_request` | Malformed authorization request | Check scopes and connection configuration |
| `unauthorized_client` | OAuth client not authorized | Verify credentials in **AgentKit** > **Connections** |
| `invalid_scope` | Scope not valid for this app | Update scopes on the connection and retry |
| `server_error` | Provider-side failure | Retry after a few minutes; check provider status |

Log both parameters in development. Do not expose raw `error_description` text to end users.

## `failed_to_exchange_token` after consent

Token exchange failed after the user approved access. See [Common scenarios on Configure connections](/agentkit/connections/#common-scenarios) for retry steps, status page checks, and what to send support.

## Redirect URI mismatch

The redirect URI in the provider's OAuth app must match the URI shown in Scalekit exactly — protocol, host, path, and trailing slashes included.

1. Open **AgentKit** > **Connections** and select the connection
2. Copy the **Redirect URI** from Scalekit
3. Paste it into the provider's OAuth app settings (Google Cloud Console, Azure portal, and similar)
4. Save both sides and restart the connection flow

> tip: Match the string exactly
>
> Watch for `http` vs `https`, missing or extra trailing slashes, and port numbers in local development.

## Session expired or invalid on the callback page

The OAuth verification session timed out before the provider redirected back. Close the window and start the connection flow again. No configuration change is required.

See also [Common scenarios on Configure connections](/agentkit/connections/#common-scenarios).

## Invalid state parameter

Scalekit validates the `state` parameter for CSRF protection. If you see this error:

1. Confirm cookies are enabled in the browser
2. Finish the flow in the same browser you started it in
3. Clear stale cookies and restart the flow
4. Check for large clock skew between client and server

## Tool execution failures

## Tool fails with an auth error but status is `ACTIVE`

Work through these checks in order:

1. Confirm status with `get_connected_account`
2. Call `refresh_connected_account` / `refreshConnectedAccount`
3. Compare `account.scopes` to the scopes your tool requires
4. Run a read-only tool (for example `gmail_get_profile`) to isolate the failure

  ### Python

```python
account = scalekit_client.actions.get_connected_account(
    identifier="user_123",
    connection_name="gmail",
)

scalekit_client.actions.refresh_connected_account(
    identifier="user_123",
    connection_name="gmail",
)

result = scalekit_client.actions.execute_tool(
    identifier="user_123",
    tool_name="gmail_get_profile",
    tool_input={},
)
print(result.data)
```

  ### Node.js

```typescript
const account = await scalekit.actions.getConnectedAccount({
  identifier: 'user_123',
  connectionName: 'gmail',
});

await scalekit.actions.refreshConnectedAccount({
  identifier: 'user_123',
  connectionName: 'gmail',
});

const result = await scalekit.actions.executeTool({
  identifier: 'user_123',
  toolName: 'gmail_get_profile',
  toolInput: {},
});
console.log(result.data);
```

## Insufficient permissions or forbidden errors

The user granted fewer scopes than your tool needs. Check granted scopes on the connected account, then send a new authorization link after you update scopes on the connection.

See [Configure scopes](/agentkit/connections/#configure-scopes) on the connections page. After you add scopes to a connection, existing users must re-authenticate.

## Provider-specific errors

## Connector works for your own account but fails for customers' accounts

Some providers restrict an OAuth app to the account that created it until the app completes the provider's review or publishing process. The connection then succeeds for your own workspace but fails for external customers, with errors such as "this app can't be used outside of development" or a provider access-denied screen.

This can affect Scalekit's prebuilt connectors too. The connector ships with a pre-filled `client_id`, and listing tools succeeds because your own account already authorized it, which can give the impression that any account can connect.

To resolve it:

1. Open the provider's developer or app settings and complete the OAuth app profile the provider requires for external use, such as the logo, terms of service, and privacy policy links. Airtable requires this in its Builder Hub. ZoomInfo requires a partner application rather than a custom (internal-only) app.
2. Confirm the app is published or verified for use beyond your own account.
3. Confirm the `client_id`, redirect URL, and scopes match exactly between the provider and **AgentKit** > **Connections**. A mismatch points the connection at a different client and fails authorization.
4. Reconnect from an external account to confirm the fix.

> note: Each provider sets its own policy
>
> The exact requirement depends on the provider's app-review policy, not on Scalekit. Check the provider's documentation for how to publish or certify an OAuth app for use by accounts other than your own.

## Google: "Access blocked" or "This app isn't verified"

Google blocks unverified apps that request sensitive scopes, or the Workspace admin blocked third-party apps.

- During development, use test users or click **Advanced** > **Go to app (unsafe)** on the consent screen
- For production, complete [Google app verification](https://support.google.com/cloud/answer/9110914) or use less restrictive scopes
- Workspace admins may need to allowlist your OAuth client

## Microsoft 365: `AADSTS65001` consent errors

The tenant has not granted consent for the permissions your connection requests.

1. Open the app registration in Azure portal
2. Confirm API permissions match your connection scopes
3. Grant admin consent if the tenant requires it
4. Retry the connection flow

## Microsoft 365: `AADSTS50020` user not found

The signed-in account is not in the expected Microsoft 365 tenant, or the tenant blocks external applications. Confirm the user has a valid work or school account and that tenant policy allows your app.

## Slack: OAuth access denied or workspace restrictions

The user may lack permission to install apps, or the workspace admin must approve the app first. Ask a workspace admin to approve the installation, or test with a workspace where you control app policy.

## OAuth works for your own account but fails for external or customer accounts

Sometimes when you create an OAuth app in your connector's provider environment, the provider sets it up in a development or testing mode that authorizes only the account that created the app. The connection then works while you test with your own account, but fails when your customers try to connect. For example, Airtable returns "OAuth app can't be used outside development," and ZoomInfo rejects a custom (internal) app.

Promote the provider app out of development mode, complete any required app profile, and re-sync the credentials. The [connector OAuth apps checklist](/agentkit/advanced/launch-checklist/#connector-oauth-apps-if-you-registered-your-own-app) lists the exact steps, and [Bring your own OAuth credentials](/agentkit/advanced/bring-your-own-oauth/) covers the setup.

## Configuration and rate limits

## Invalid client or client authentication failed

OAuth credentials on the connection do not match the provider's console.

1. Open **AgentKit** > **Connections** and select the connection
2. Compare **Client ID** and **Client Secret** to the provider's OAuth app
3. Regenerate the secret in the provider console if it may have rotated
4. Create a new connected account and retry OAuth

## Authorization succeeds but tools fail on scope

The connection is missing scopes your tools require. Update scopes in the connection form, then have users re-authenticate. Scopes on existing tokens do not expand automatically.

## Rate limit or quota exceeded

The provider rejected requests because you exceeded its quota. Back off and retry with exponential delay, reduce call frequency, and cache read results where possible.

Bring Your Own Credentials (BYOC) gives you a dedicated quota on providers that support separate OAuth apps. See your connector's setup guide for BYOC steps.

## Get help

Open **AgentKit** > **Connected Accounts** in the dashboard and review status, refresh history, and tool execution logs for the affected account.

When you contact [support](mailto:support@scalekit.com), include:

- Connected account ID or user `identifier`
- Connection name (for example `gmail`, `slack`)
- Full error text and timestamp
- Steps that reproduce the failure

Related guides:

- [Configure connections](/agentkit/connections/) — setup, scopes, and common OAuth errors
- [Manage connected accounts](/agentkit/connected-accounts/) — per-user connection state and credentials


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |