Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
Docs: Add troubleshooting section (#2022)
Sushmitha Malleshfd169d7faa56
diff --git a/fern/docs.yml b/fern/docs.ymlindex 9ffc8cab1..b796a18b4 100644--- a/fern/docs.yml+++ b/fern/docs.yml@@ -190,6 +190,33 @@ navigation:- page: Migration Guidepath: pages/dist/migration-guide.mdxslug: migration+ - section: Troubleshooting+ slug: troubleshooting+ contents:+ - page: Overview+ path: pages/src/troubleshooting/overview.mdx+ slug: overview+ - page: API+ path: pages/src/troubleshooting/api.mdx+ slug: api+ - page: Authentication+ path: pages/src/troubleshooting/authentication.mdx+ slug: authentication+ - page: Dashboard+ path: pages/src/troubleshooting/dashboard.mdx+ slug: dashboard+ - page: MCP+ path: pages/src/troubleshooting/mcp.mdx+ slug: mcp+ - page: SDKs+ path: pages/src/troubleshooting/sdks.mdx+ slug: sdks+ - page: Tools & Toolkits+ path: pages/src/troubleshooting/tools.mdx+ slug: tools+ - page: Triggers+ path: pages/src/troubleshooting/triggers.mdx+ slug: triggers- tab: exampleslayout:- section: Getting Starteddiff --git a/fern/pages/src/troubleshooting/api.mdx b/fern/pages/src/troubleshooting/api.mdxnew file mode 100644index 000000000..805e3ce8a--- /dev/null+++ b/fern/pages/src/troubleshooting/api.mdx@@ -0,0 +1,21 @@+---+title: API+subtitle: Debugging and troubleshooting API issues+image: "https://og.composio.dev/api/og?title=API%20Troubleshooting"+keywords: 'api, rest, troubleshooting, curl, debugging'+hide-nav-links: true+---++## Reporting API issues++When reporting API issues to support, provide the following:++- **cURL command**: Include the exact cURL to reproduce the issue+- **Request ID**: Add `x-request-id: <uuid>` header to your request and share the UUID (generate at [uuidgenerator.net](https://www.uuidgenerator.net/))+- **Error details**: Share the complete error message+- **Reproduction steps**: Include any steps needed to reproduce the issue++## Getting help++- **Email**: [email protected]+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)\ No newline at end of filediff --git a/fern/pages/src/troubleshooting/authentication.mdx b/fern/pages/src/troubleshooting/authentication.mdxnew file mode 100644index 000000000..30204cf18--- /dev/null+++ b/fern/pages/src/troubleshooting/authentication.mdx@@ -0,0 +1,45 @@+---+title: Authentication+subtitle: Debugging and troubleshooting authentication issues+image: "https://og.composio.dev/api/og?title=Authentication%20Troubleshooting"+keywords: 'authentication, oauth, connections, scopes, troubleshooting'+hide-nav-links: true+---++## Using Composio's default OAuth app++When using our default OAuth configuration:++- **Don't add additional scopes** - They may not be approved in our OAuth app+- Use only the pre-configured scopes provided++## Using custom OAuth apps++Ensure your OAuth app is configured correctly:++- **Redirect URL**: Must match exactly what's configured in your OAuth provider+- **Scopes**: Auth config scopes must match your OAuth app configuration+- **Credentials**: Verify client ID and secret are correct++For setup guides by toolkit: [OAuth Configuration Guides](https://composio.dev/oauth)++## Common authentication issues++- **Invalid redirect URI**: Check the callback URL matches exactly+- **Scope mismatch**: Ensure requested scopes are configured in both auth config and OAuth app+- **Expired tokens**: Try refreshing the connection+- **Rate limits**: Some providers limit authentication attempts++## Reporting authentication issues++When reporting to support, provide:++- **Error message**: Complete error details and screenshots+- **Auth config ID**: The `authConfigId` being used+- **Connected account ID**: If a connection was already created+- **OAuth provider**: Which service you're trying to connect++## Getting help++- **Email**: [email protected]+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)\ No newline at end of filediff --git a/fern/pages/src/troubleshooting/dashboard.mdx b/fern/pages/src/troubleshooting/dashboard.mdxnew file mode 100644index 000000000..89736794c--- /dev/null+++ b/fern/pages/src/troubleshooting/dashboard.mdx@@ -0,0 +1,23 @@+---+title: Dashboard+subtitle: Debugging and troubleshooting dashboard issues+image: "https://og.composio.dev/api/og?title=Dashboard%20Troubleshooting"+keywords: 'dashboard, platform, UI, troubleshooting, debugging'+hide-nav-links: true+---++## Reporting dashboard issues++When reporting dashboard issues to support, provide:++- **Screenshot or recording**: Visual evidence of the issue+- **Error details**: Complete error message shown in the UI+- **Network logs**: Check browser DevTools for failing API calls and share:+ - Error message+ - Request ID (`x-request-id` header)+ - Failed endpoint URL++## Getting help++- **Email**: [email protected]+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)\ No newline at end of filediff --git a/fern/pages/src/troubleshooting/mcp.mdx b/fern/pages/src/troubleshooting/mcp.mdxnew file mode 100644index 000000000..029f73c13--- /dev/null+++ b/fern/pages/src/troubleshooting/mcp.mdx@@ -0,0 +1,51 @@+---+title: MCP+subtitle: Debugging and troubleshooting MCP server issues+image: "https://og.composio.dev/api/og?title=MCP%20Troubleshooting"+keywords: 'mcp, model context protocol, server, troubleshooting, debugging'+hide-nav-links: true+---++## Connected account not found error++This error occurs when MCP cannot find a valid connected account for authentication:++- **Specify an account**: Provide either `connected_account_id` or `user_id` in your MCP configuration+- **Default behavior**: Without specification, MCP uses `user_id=default`. If multiple connections exist with the same user_id, the most recent is used+- **Verification checklist**:+ - Account status is `ACTIVE` (not deleted)+ - Account belongs to the same auth config used to create the MCP server++Learn more: [MCP Developer Guide](/docs/mcp-developers#client-applications-connect-to-the-server)++## Getting 404 errors++Verify your URL format matches one of these patterns:++- `https://mcp.composio.dev/composio/server/<UUID>/mcp`+- `https://apollo-<randomID>-composio.vercel.app/v3/mcp/<UUID>`+- `https://apollo.composio.dev/v3/mcp/<UUID>`++## Testing and debugging++If experiencing issues, test your MCP server with:++- [Postman MCP Requests](https://learning.postman.com/docs/postman-ai-developer-tools/mcp-requests/create/)+- [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector)++This helps identify whether the issue is with your MCP client or the server.++## Reporting MCP issues++When reporting to support, provide:++- **Error message**: Complete error details+- **MCP server URL**: The exact URL you're connecting to+- **Testing results**: Whether issue reproduces in MCP Inspector/Postman or only in specific client+- **Connected account ID**: If facing connection issues+- **Reproduction steps**: Clear steps to reproduce the issue++## Getting help++- **Email**: [email protected]+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)\ No newline at end of filediff --git a/fern/pages/src/troubleshooting/overview.mdx b/fern/pages/src/troubleshooting/overview.mdxnew file mode 100644index 000000000..ea9faa33a--- /dev/null+++ b/fern/pages/src/troubleshooting/overview.mdx@@ -0,0 +1,58 @@+---+title: Troubleshooting+subtitle: Common issues and quick links+image: "https://og.composio.dev/api/og?title=Troubleshooting"+keywords: 'troubleshooting, errors, issues, debugging, problems'+hide-nav-links: true+---++This section is designed to help you quickly identify and resolve common issues encountered with the Composio.++Some quick links:+<Card+ title="Report issues"+ icon="fa-solid fa-bug"+ href="https://github.com/ComposioHQ/composio/issues/new?labels=bug"+>+ Found a bug? Please create a Github issue!+</Card>++<Card+ title="Ask AI"+ icon="fa-solid fa-brain"+ href="https://deepwiki.com/ComposioHQ/composio"+>+ Try to use Ask AI in the docs or deepwiki to get the fastes responses on features, types, and best practices.+</Card>++<Card+ title="Feature requests"+ icon="fa-solid fa-sparkles"+ href="https://github.com/ComposioHQ/composio/issues/new?labels=enhancement"+>+ Have an idea for improving Composio? Share your feature suggestions with us and we will prioritise your requests+</Card>++<Card+ title="Ask the community"+ icon="fa-solid fa-comments"+ href="https://github.com/ComposioHQ/composio/discussions"+>+ Join our GitHub discussions to get help from the community+</Card>++<Card+ title="Discord community"+ icon="fa-brands fa-discord"+ href="https://discord.com/channels/1170785031560646836/1268871288156323901"+>+ Post support queries on our discord channel or reachout to [email protected]+</Card>++<Card+ title="Migration guides"+ icon="fa-solid fa-book"+ href="/docs/migration"+>+ Check out our migration guides to help you upgrade to the latest version.+</Card>\ No newline at end of filediff --git a/fern/pages/src/troubleshooting/sdks.mdx b/fern/pages/src/troubleshooting/sdks.mdxnew file mode 100644index 000000000..d92dabf4e--- /dev/null+++ b/fern/pages/src/troubleshooting/sdks.mdx@@ -0,0 +1,50 @@+---+title: SDKs+subtitle: Debugging and troubleshooting SDK issues+image: "https://og.composio.dev/api/og?title=SDK%20Troubleshooting"+keywords: 'sdk, python, typescript, troubleshooting, debugging'+hide-nav-links: true+---++## Debug network issues++Enable debug logging to see API calls and identify if issues are SDK or API related. Look for the `requestId` in logs to share with support.++<CodeGroup>+```python Python+# Set environment variable+COMPOSIO_LOGGING_LEVEL=debug+```+```typescript TypeScript+// Set environment variable+COMPOSIO_LOG_LEVEL=debug+```+</CodeGroup>++## Check SDK version++Ensure you're using the latest version:++<CodeGroup>+```bash Python+pip install --upgrade composio+```+```bash TypeScript+npm install @composio/core@latest+```+</CodeGroup>++Check current version:+- Python: [PyPI](https://pypi.org/project/composio/)+- TypeScript: [npm](https://www.npmjs.com/package/@composio/core)++## Common issues++- **Type errors or parameter confusion**: Search [DeepWiki](https://deepwiki.com/ComposioHQ/composio) or use the Ask AI assistant+- **Tool-specific issues**: Check the [specific tool's documentation](/toolkits)+- **Bug reporting**: Create a [GitHub issue](https://github.com/ComposioHQ/composio/issues/new?labels=bug) with debug logs and reproduction steps++## Getting help++- **Email**: [email protected]+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)\ No newline at end of filediff --git a/fern/pages/src/troubleshooting/tools.mdx b/fern/pages/src/troubleshooting/tools.mdxnew file mode 100644index 000000000..7e7dc6011--- /dev/null+++ b/fern/pages/src/troubleshooting/tools.mdx@@ -0,0 +1,55 @@+---+title: Tools & Toolkits+subtitle: Debugging and troubleshooting tool execution issues+image: "https://og.composio.dev/api/og?title=Tools%20Troubleshooting"+keywords: 'tools, toolkits, execution, permissions, troubleshooting'+hide-nav-links: true+---++## Tool execution failures (401/403 errors)++Authentication and permission errors typically occur due to:++### Missing scopes++Check if your connection has the required scopes using this API:++```bash+curl --location 'https://backend.composio.dev/api/v3/tools/get_scopes_required' \+--header 'x-api-key: YOUR_COMPOSIO_API_KEY' \+--header 'Content-Type: application/json' \+--data '{+ "tools": [+ "SLACK_SENDS_A_MESSAGE_TO_A_SLACK_CHANNEL",+ "SLACK_CREATE_A_REMINDER"+ ]+}'+```++### Insufficient permissions++Verify the connected account has necessary permissions:++- **Admin requirements**: Some tools require admin-level access+- **Paid accounts**: Certain toolkits need paid subscriptions+ - Example: MS Teams requires Microsoft 365 account + Azure AD tenant++## Tool not working++- Check [tool-specific documentation](/toolkits) for requirements+- Verify the connected account is active and properly authenticated+- Test with the latest SDK version++## Reporting tool issues++When reporting to support, provide:++- **Error message**: Complete error details+- **Log ID**: From the error response+- **Tool name**: Exact tool slug being executed+- **Connected account ID**: Account used for execution++## Getting help++- **Email**: [email protected]+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)\ No newline at end of filediff --git a/fern/pages/src/troubleshooting/triggers.mdx b/fern/pages/src/troubleshooting/triggers.mdxnew file mode 100644index 000000000..54f7b4758--- /dev/null+++ b/fern/pages/src/troubleshooting/triggers.mdx@@ -0,0 +1,36 @@+---+title: Triggers+subtitle: Debugging and troubleshooting trigger issues+image: "https://og.composio.dev/api/og?title=Triggers%20Troubleshooting"+keywords: 'triggers, webhooks, events, troubleshooting, debugging'+hide-nav-links: true+---++## Unable to create trigger++Check the error message - the account might not have sufficient permissions or required scopes.++## Type errors with trigger payloads++Having issues with trigger payload types? Search [DeepWiki](https://deepwiki.com/ComposioHQ/composio) or use the Ask AI assistant for type definitions and examples.++## Not receiving trigger payloads++Even if the action occurred (email received, Jira issue created, etc.), there may be delays:++- **Gmail triggers**: Uses polling with minimum 1-minute frequency - expect delays of up to a minute+- **Other services**: May have their own polling intervals or webhook delivery delays++## Reporting trigger issues++When reporting to support, provide:++- **Error message**: Complete error details+- **Connected account**: The account ID used for creating the trigger+- **cURL command**: To reproduce the issue+- **Reproduction steps**: Any additional steps needed++## Getting help++- **Email**: [email protected]+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)\ No newline at end of file