Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
md 85 lines 5.72 KB
Rendered Raw
1 # Errors and provider gotchas
2
3 Use this guide for failures shared by Composio For You and Composio Platform. Keep product-specific credential and client setup in the selected product guide.
4
5 ## Start with evidence
6
7 Get the Composio log or request ID and inspect Dashboard Logs before changing credentials or code. Agent frameworks often wrap the underlying provider error.
8
9 When the CLI is already installed and authenticated for the applicable product, these commands can provide additional evidence:
10
11 ```bash
12 composio dev logs tools
13 composio dev logs triggers
14 composio connections list
15 ```
16
17 Do not install or reinitialize the CLI solely to diagnose a dashboard log that already contains the failure.
18
19 ## Tool does not exist
20
21 Never guess a slug. In a Platform session, discover tools through the session meta tools. In a CLI workflow, use `composio search`, then inspect the returned tool.
22
23 For legacy manual execution, a missing tool may be a toolkit-version problem. Fetch current migration and execution docs rather than assuming the provider lacks the operation. New session integrations should use runtime discovery.
24
25 ## Tool call paused or blocked by session policy
26
27 Some results are the session working as configured, not failures. Check the result type before diagnosing auth or the provider:
28
29 - **`input_required`** (`ToolInputRequiredError` in Python, `ComposioToolInputRequiredError` in TypeScript): an [Approvals](https://docs.composio.dev/docs/approvals.md) rule gated the tool. It didn't run. Ask the user, then retry with `input_responses` and `request_state`. Over MCP, a client without elicitation support gets these calls denied.
30 - **`blocked`** with `Blocked by session policy`: a [Firewall](https://docs.composio.dev/docs/firewall.md) hook matched. `block_reason` and `hook_results` name the hook. Don't reconnect the account or retry the same call. Change the request, or change the hook if it blocked something it shouldn't.
31
32 ## Custom MCP tools missing
33
34 If a `CUSTOM_*` toolkit synced but its tools don't appear in search, list the toolkit's tools directly or fetch them with `COMPOSIO_GET_TOOL_SCHEMAS`, then call the tool by slug. Resyncing doesn't fix search. If the v3 tools API returns an empty list, use v3.1 or request the latest toolkit version. See [Custom MCP troubleshooting](https://docs.composio.dev/docs/extending-sessions/custom-mcp.md).
35
36 ## Identify the authentication boundary
37
38 ### Composio project or session 401
39
40 This happens before a provider tool call succeeds. The Platform project credential may be missing, masked, invalid, or associated with a different project.
41
42 Re-run the no-output credential checks from the Platform guide. Do not print, rotate, replace, or request the key in chat. If the developer arrived from Dashboard Getting Started, direct them back to that project's Step 1 rather than running `composio dev init`.
43
44 ### Provider connected-account 401
45
46 This appears on a real tool execution after the project and session reached the provider. The selected user's provider token may be revoked, expired, or invalidated by a password, 2FA, consent, or administrator-policy change.
47
48 Keep the same project key and application user ID. Generate a fresh Connect Link for that integration, reconnect the provider account, and retry the safe call. If a link expired, request a new one.
49
50 ### No active connection on a sibling toolkit
51
52 A `NoActiveConnection` error can appear when the user connected one toolkit of a product's App but the execution targets its sibling: the connection is on `notion` while the tool belongs to `notion_mcp`, or the reverse. Sibling toolkits never share a connection. Link the exact toolkit the tool belongs to. If you choose an already-connected sibling instead, rediscover its tools and inspect their schemas before calling them; sibling tool slugs and inputs are not interchangeable.
53
54 ### For You client authentication
55
56 If the MCP client itself cannot authenticate, verify the consumer endpoint, OAuth session, or `ck_...` header path from the For You guide. Do not substitute a Platform project key.
57
58 ## Common provider constraints
59
60 - **Google "App is blocked":** remove unnecessary scopes or use a verified custom OAuth app.
61 - **Google API disabled:** enable the required provider API in the Google Cloud project that owns the custom credentials.
62 - **Slack 429:** managed apps share provider quota; use a custom Slack app for a dedicated bucket when needed.
63 - **Microsoft 403:** the tenant may require administrator consent.
64 - **GitHub App access:** OAuth credentials and repository installation are separate steps.
65 - **Payment toolkit session restriction:** treat it as a surface policy restriction, not a plan or connection failure.
66
67 ## Branding and production auth
68
69 Managed auth works in production and is the fastest way to start. Recommend your own OAuth app when the application needs its own branding, its own scopes, or dedicated provider rate limits.
70
71 When someone asks to remove Composio branding, identify the surface first: Connect Link page, provider consent screen, secured badge, callback domain, or success page. They have different fixes. Fetch `white-labeling-authentication.md` before proposing an implementation.
72
73 ## Triggers and webhooks
74
75 Check the Composio status page and trigger logs before changing a trigger. Use current trigger documentation for event names, polling limits, and connection-state verification. Do not promise static outbound IPs; use documented webhook signature verification.
76
77 ## Canonical follow-up
78
79 For provider- or toolkit-specific behavior, fetch:
80
81 ```text
82 https://docs.composio.dev/toolkits/<toolkit>.md
83 ```
84
85 For APIs, migrations, triggers, or compliance questions, find the current page through `https://docs.composio.dev/llms.txt`. If the problem remains unresolved, include the log ID when escalating to Composio support.