> **Building with AI coding agents?** If you're using an AI coding agent, install the official Scalekit plugin. It gives your agent full awareness of the Scalekit API — reducing hallucinations and enabling faster, more accurate code generation.
>
> - **Claude Code**: `claude plugin marketplace add scalekit-inc/claude-code-authstack && claude plugin install <auth-type>@scalekit-auth-stack`
> - **GitHub Copilot CLI**: `copilot plugin marketplace add scalekit-inc/github-copilot-authstack` then `copilot plugin install <auth-type>@scalekit-auth-stack`
> - **Codex**: run the bash installer, restart, then open Plugin Directory and enable `<auth-type>`
> - **Skills CLI** (Windsurf, Cline, 40+ agents): `npx skills add scalekit-inc/skills --list` then `--skill <skill-name>`
>
> `<auth-type>` / `<skill-name>`: `agentkit`, `full-stack-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

## 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.

## 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 |