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
update(docs): update troubleshooting guide
Uday-sidagana7815b16f3fbe
diff --git a/docs/content/docs/troubleshooting/api.mdx b/docs/content/docs/troubleshooting/api.mdxindex 376cafc7c..576f1938f 100644--- a/docs/content/docs/troubleshooting/api.mdx+++ b/docs/content/docs/troubleshooting/api.mdx@@ -9,7 +9,27 @@ 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++ <img+ src="/images/troubleshooting/troubleshooting-enable-request-id-api.png"+ alt="Example of `x-request-id` header"+ style={{ maxWidth: '800px', width: '100%', marginTop: '12px', marginLeft: '0.5rem', borderRadius: '8px', display: 'block' }}+ />++- **Error details**: Share the complete error message. For example:++ ```json+ {+ "error": {+ "message": "Validation error while processing request",+ "error_code": 10400,+ "suggested_fix": "Please check the payload.",+ "errors": [+ "Error in payload.text.arguments: Only one of 'text' or 'arguments' must be provided"+ ]+ }+ }+ ```- **Reproduction steps**: Include any steps needed to reproduce the issue## Getting helpdiff --git a/docs/content/docs/troubleshooting/authentication.mdx b/docs/content/docs/troubleshooting/authentication.mdxindex 6357f0b15..b471510a2 100644--- a/docs/content/docs/troubleshooting/authentication.mdx+++ b/docs/content/docs/troubleshooting/authentication.mdx@@ -32,9 +32,22 @@ For setup guides by toolkit: [OAuth Configuration Guides](https://composio.dev/oWhen 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+- **Error message**: Complete error details and screenshots. For example:++ <img+ src="/images/troubleshooting/troubleshooting-auth-app-blocked.png"+ alt="Example: This app is blocked error screen shown by Google when un-verified sensitive scopes are configured"+ style={{ maxWidth: '640px', width: '100%', marginTop: '12px', marginLeft: '0.5rem', borderRadius: '8px', display: 'block' }}+ />++- **Auth config and account IDs**: Include the `authConfigId` used for the request and, if a connection already exists, the `connected_account_id`++ <img+ src="/images/troubleshooting/troubleshooting-auth-config-id.png"+ alt="Finding authConfigId and connected account ID in the Composio dashboard"+ style={{ maxWidth: '900px', width: '100%', marginTop: '12px', marginLeft: '0.5rem', borderRadius: '8px', display: 'block' }}+ />+- **OAuth provider**: Which service you're trying to connect## Getting helpdiff --git a/docs/content/docs/troubleshooting/dashboard.mdx b/docs/content/docs/troubleshooting/dashboard.mdxindex 2b675ec20..1b0165bec 100644--- a/docs/content/docs/troubleshooting/dashboard.mdx+++ b/docs/content/docs/troubleshooting/dashboard.mdx@@ -8,11 +8,31 @@ description: Troubleshooting dashboard issuesWhen reporting dashboard issues to support, provide:- **Screenshot or recording**: Visual evidence of the issue-- **Error details**: Complete error message shown in the UI+- **Error details**: Complete error message shown in the UI. For example:++ <img+ src="/images/troubleshooting/troubleshooting-dashboard-ui-error.png"+ alt="Example dashboard UI error: A project with this name already exists"+ style={{ maxWidth: '640px', width: '100%', marginTop: '12px', marginLeft: '0.5rem', borderRadius: '8px', display: 'block' }}+ />+- **Network logs**: Check browser DevTools for failing API calls and share:- Error message- Request ID (`x-request-id` header)- - Failed endpoint URL++ <img+ src="/images/troubleshooting/troubleshooting-dashboard-request-id.png"+ alt="Tool call error"+ style={{ maxWidth: '720px', width: '100%', marginTop: '12px', marginLeft: '0.5rem', borderRadius: '8px', display: 'block' }}+ />++ - Failed endpoint URL (`https://backend.composio.dev/api/v3/org/project/new`)++ <img+ src="/images/troubleshooting/troubleshooting-dashboard-rename-error.jpg"+ alt="Example network log and dashboard error for a failed tool call"+ style={{ maxWidth: '720px', width: '100%', marginTop: '12px', marginLeft: '0.5rem', borderRadius: '8px', display: 'block' }}+ />## Getting helpdiff --git a/docs/content/docs/troubleshooting/index.mdx b/docs/content/docs/troubleshooting/index.mdxindex fffb65062..b1590956f 100644--- a/docs/content/docs/troubleshooting/index.mdx+++ b/docs/content/docs/troubleshooting/index.mdx@@ -3,7 +3,7 @@ title: Troubleshootingdescription: Common issues and quick links----import { Bug, Brain, Sparkles, MessageCircle, MessageSquare, BookOpen } from 'lucide-react';+import { Bug, Brain, Sparkles, MessageCircle, MessageSquare, BookOpen, Mail } from 'lucide-react';This section is designed to help you quickly identify and resolve common issues encountered with Composio.@@ -23,7 +23,10 @@ Some quick links:Join our GitHub discussions to get help from the community</Card><Card title="Discord community" href="https://discord.com/channels/1170785031560646836/1268871288156323901" icon={<MessageSquare />}>- Post support queries on our discord channel or reach out to [email protected]+ Post support queries on our discord channel+ </Card>+ <Card title="Contact Support" href="mailto:[email protected]" icon={<Mail />}>+ Reach out to support for account, billing, or escalations</Card><Card title="Migration guides" href="/docs/migration-guide" icon={<BookOpen />}>Check out our migration guides to help you upgrade to the latest version.diff --git a/docs/content/docs/troubleshooting/mcp.mdx b/docs/content/docs/troubleshooting/mcp.mdxindex 0a5764d06..6dea95d56 100644--- a/docs/content/docs/troubleshooting/mcp.mdx+++ b/docs/content/docs/troubleshooting/mcp.mdx@@ -13,7 +13,7 @@ This error occurs when MCP cannot find a valid connected account for authenticat- Account status is `ACTIVE` (not deleted)- Account belongs to the same auth config used to create the MCP server-Learn more: [Single Toolkit MCP](/docs/single-toolkit-mcp)+Learn more: [MCP Developer Guide](/docs/mcp-developers#client-applications-connect-to-the-server)## Getting 404 errors@@ -37,9 +37,21 @@ This helps identify whether the issue is with your MCP client or the server.When reporting to support, provide:- **Error message**: Complete error details-- **MCP server URL**: The exact URL you're connecting to+- **MCP server URL**: The exact URL you're connecting to and the corresponding `mcp_server_id`++ <img+ src="/images/troubleshooting/troubleshooting-mcp-server-url.png"+ alt="Example MCP server URL shown in the Composio dashboard"+ style={{ maxWidth: '720px', width: '100%', marginTop: '12px', marginLeft: '0.5rem', borderRadius: '8px', display: 'block' }}+ />- **Testing results**: Whether issue reproduces in MCP Inspector/Postman or only in specific client- **Connected account ID**: If facing connection issues++ <img+ src="/images/troubleshooting/troubleshooting-mcp-connected-account-id.png"+ alt="Example connected account ID used for MCP authentication"+ style={{ maxWidth: '720px', width: '100%', marginTop: '12px', marginLeft: '0.5rem', borderRadius: '8px', display: 'block' }}+ />- **Reproduction steps**: Clear steps to reproduce the issue## Getting helpdiff --git a/docs/content/docs/troubleshooting/sdks.mdx b/docs/content/docs/troubleshooting/sdks.mdxindex 25915c9c5..15c522909 100644--- a/docs/content/docs/troubleshooting/sdks.mdx+++ b/docs/content/docs/troubleshooting/sdks.mdx@@ -5,7 +5,7 @@ description: Troubleshooting SDK issues## Debug network issues-Enable debug logging to see API calls and identify if issues are SDK or API related. Look for the `x-request-id` in logs to share with support.+Enable debug logging to see API calls and identify if issues are SDK or API related. When contacting support, share the full debug logs **along with** the `x-request-id`.<Tabs groupId="language" items={['Python', 'TypeScript']} persist><Tab value="Python">@@ -22,6 +22,24 @@ COMPOSIO_LOG_LEVEL=debug</Tab></Tabs>+Once debug logging is enabled, you can find the `x-request-id` in your SDK logs:++- **Python SDK example**++ <img+ src="/images/troubleshooting/troubleshooting-sdk-py-request-id.png"+ alt="Example of x-request-id highlighted in Python SDK debug logs"+ style={{ maxWidth: '720px', width: '100%', marginTop: '12px', marginLeft: '0.5rem', borderRadius: '8px', display: 'block' }}+ />++- **TypeScript SDK example**++ <img+ src="/images/troubleshooting/troubleshooting-sdk-ts-request-id.png"+ alt="Example of x-request-id highlighted in TypeScript SDK debug logs"+ style={{ maxWidth: '720px', width: '100%', marginTop: '12px', marginLeft: '0.5rem', borderRadius: '8px', display: 'block' }}+ />+## Check SDK versionEnsure you're using the latest version:diff --git a/docs/content/docs/troubleshooting/tools.mdx b/docs/content/docs/troubleshooting/tools.mdxindex d46ce67a7..f4664c93b 100644--- a/docs/content/docs/troubleshooting/tools.mdx+++ b/docs/content/docs/troubleshooting/tools.mdx@@ -41,10 +41,31 @@ Verify the connected account has necessary permissions: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++- **Error message**: Complete error details. For example:++ ```json+ {+ "data": {+ "message": "{\n \"error\": {\n \"code\": 404,\n \"message\": \"Requested entity was not found.\",\n \"errors\": [\n {\n \"message\": \"Requested entity was not found.\",\n \"domain\": \"global\",\n \"reason\": \"notFound\"\n }\n ],\n \"status\": \"NOT_FOUND\"\n+ }\n+}\n",+ "status_code": 404+ },+ "successful": false,+ "error": "404 Client Error: Not Found for url: https://gmail.googleapis.com/gmail/v1/users/me/messages/123456?format=full",+ "log_id": "log_tVqomBgg11-t"+ }+ ```++- **Log ID**: From the error response.++ <img+ src="/images/troubleshooting/troubleshooting-tool-log-id.png"+ alt="Example tool execution log showing log_id in the Composio dashboard"+ style={{ maxWidth: '720px', width: '100%', marginTop: '12px', marginLeft: '0.5rem', borderRadius: '8px', display: 'block' }}+ />++- **Tool name**: Exact tool slug being executed (for example, `GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID`)+- **Connected account ID**: Account used for execution (for example, `ca_xxx`)## Getting helpdiff --git a/docs/content/docs/troubleshooting/triggers.mdx b/docs/content/docs/troubleshooting/triggers.mdxindex f85d666d7..9011281dd 100644--- a/docs/content/docs/troubleshooting/triggers.mdx+++ b/docs/content/docs/troubleshooting/triggers.mdx@@ -23,9 +23,15 @@ Even if the action occurred (email received, Jira issue created, etc.), there maWhen 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+- **Connected account and trigger IDs**: The connected account ID used for creating the trigger and the specific trigger ID that's failing++ <img+ src="/images/troubleshooting/troubleshooting-trigger-id.png"+ alt="Example of trigger ID and connected account ID in the Composio dashboard"+ style={{ maxWidth: '720px', width: '100%', marginTop: '12px', marginLeft: '0.5rem', borderRadius: '8px', display: 'block' }}+ />++- **Reproduction steps**: Clear, step-by-step instructions to reproduce the issue, including key trigger configuration details (for example, the `interval`)## Getting helpdiff --git a/docs/public/images/troubleshooting/troubleshooting-auth-app-blocked.png b/docs/public/images/troubleshooting/troubleshooting-auth-app-blocked.pngnew file mode 100644index 000000000..096e8b14bBinary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-auth-app-blocked.png differdiff --git a/docs/public/images/troubleshooting/troubleshooting-auth-config-id.png b/docs/public/images/troubleshooting/troubleshooting-auth-config-id.pngnew file mode 100644index 000000000..7610fa982Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-auth-config-id.png differdiff --git a/docs/public/images/troubleshooting/troubleshooting-dashboard-rename-error.jpg b/docs/public/images/troubleshooting/troubleshooting-dashboard-rename-error.jpgnew file mode 100644index 000000000..6cee079e3Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-dashboard-rename-error.jpg differdiff --git a/docs/public/images/troubleshooting/troubleshooting-dashboard-request-id.png b/docs/public/images/troubleshooting/troubleshooting-dashboard-request-id.pngnew file mode 100644index 000000000..536ddae1fBinary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-dashboard-request-id.png differdiff --git a/docs/public/images/troubleshooting/troubleshooting-dashboard-ui-error.png b/docs/public/images/troubleshooting/troubleshooting-dashboard-ui-error.pngnew file mode 100644index 000000000..10a020816Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-dashboard-ui-error.png differdiff --git a/docs/public/images/troubleshooting/troubleshooting-enable-request-id-api.png b/docs/public/images/troubleshooting/troubleshooting-enable-request-id-api.pngnew file mode 100644index 000000000..3ea065f7dBinary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-enable-request-id-api.png differdiff --git a/docs/public/images/troubleshooting/troubleshooting-mcp-connected-account-id.png b/docs/public/images/troubleshooting/troubleshooting-mcp-connected-account-id.pngnew file mode 100644index 000000000..cf9abc1ceBinary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-mcp-connected-account-id.png differdiff --git a/docs/public/images/troubleshooting/troubleshooting-mcp-server-url.png b/docs/public/images/troubleshooting/troubleshooting-mcp-server-url.pngnew file mode 100644index 000000000..5216160d1Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-mcp-server-url.png differdiff --git a/docs/public/images/troubleshooting/troubleshooting-sdk-py-request-id.png b/docs/public/images/troubleshooting/troubleshooting-sdk-py-request-id.pngnew file mode 100644index 000000000..ae3b388d3Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-sdk-py-request-id.png differdiff --git a/docs/public/images/troubleshooting/troubleshooting-sdk-ts-request-id.png b/docs/public/images/troubleshooting/troubleshooting-sdk-ts-request-id.pngnew file mode 100644index 000000000..19751fa5fBinary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-sdk-ts-request-id.png differdiff --git a/docs/public/images/troubleshooting/troubleshooting-tool-log-id.png b/docs/public/images/troubleshooting/troubleshooting-tool-log-id.pngnew file mode 100644index 000000000..e49d95287Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-tool-log-id.png differdiff --git a/docs/public/images/troubleshooting/troubleshooting-trigger-id.png b/docs/public/images/troubleshooting/troubleshooting-trigger-id.pngnew file mode 100644index 000000000..9f94c5632Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-trigger-id.png differ