Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Errors and provider gotchas
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.
Start with evidence
Get the Composio log or request ID and inspect Dashboard Logs before changing credentials or code. Agent frameworks often wrap the underlying provider error.
When the CLI is already installed and authenticated for the applicable product, these commands can provide additional evidence:
composio dev logs tools
composio dev logs triggers
composio connections list
Do not install or reinitialize the CLI solely to diagnose a dashboard log that already contains the failure.
Tool does not exist
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.
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.
Tool call paused or blocked by session policy
Some results are the session working as configured, not failures. Check the result type before diagnosing auth or the provider:
input_required(ToolInputRequiredErrorin Python,ComposioToolInputRequiredErrorin TypeScript): an Approvals rule gated the tool. It didn't run. Ask the user, then retry withinput_responsesandrequest_state. Over MCP, a client without elicitation support gets these calls denied.blockedwithBlocked by session policy: a Firewall hook matched.block_reasonandhook_resultsname 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.
Custom MCP tools missing
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.
Identify the authentication boundary
Composio project or session 401
This happens before a provider tool call succeeds. The Platform project credential may be missing, masked, invalid, or associated with a different project.
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.
Provider connected-account 401
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.
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.
No active connection on a sibling toolkit
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.
For You client authentication
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.
Common provider constraints
- Google "App is blocked": remove unnecessary scopes or use a verified custom OAuth app.
- Google API disabled: enable the required provider API in the Google Cloud project that owns the custom credentials.
- Slack 429: managed apps share provider quota; use a custom Slack app for a dedicated bucket when needed.
- Microsoft 403: the tenant may require administrator consent.
- GitHub App access: OAuth credentials and repository installation are separate steps.
- Payment toolkit session restriction: treat it as a surface policy restriction, not a plan or connection failure.
Branding and production auth
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.
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.
Triggers and webhooks
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.
Canonical follow-up
For provider- or toolkit-specific behavior, fetch:
https://docs.composio.dev/toolkits/<toolkit>.md
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.