Skip to content

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

update(docs): update troubleshooting guide

Uday-sidagana7815b16f3fbe
diff --git a/docs/content/docs/troubleshooting/api.mdx b/docs/content/docs/troubleshooting/api.mdx
index 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 help
diff --git a/docs/content/docs/troubleshooting/authentication.mdx b/docs/content/docs/troubleshooting/authentication.mdx
index 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/o
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
+- **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 help
diff --git a/docs/content/docs/troubleshooting/dashboard.mdx b/docs/content/docs/troubleshooting/dashboard.mdx
index 2b675ec20..1b0165bec 100644
--- a/docs/content/docs/troubleshooting/dashboard.mdx
+++ b/docs/content/docs/troubleshooting/dashboard.mdx
@@ -8,11 +8,31 @@ description: Troubleshooting 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
+- **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 help
diff --git a/docs/content/docs/troubleshooting/index.mdx b/docs/content/docs/troubleshooting/index.mdx
index fffb65062..b1590956f 100644
--- a/docs/content/docs/troubleshooting/index.mdx
+++ b/docs/content/docs/troubleshooting/index.mdx
@@ -3,7 +3,7 @@ title: Troubleshooting
description: 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.mdx
index 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 help
diff --git a/docs/content/docs/troubleshooting/sdks.mdx b/docs/content/docs/troubleshooting/sdks.mdx
index 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 version
Ensure you're using the latest version:
diff --git a/docs/content/docs/troubleshooting/tools.mdx b/docs/content/docs/troubleshooting/tools.mdx
index 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 help
diff --git a/docs/content/docs/troubleshooting/triggers.mdx b/docs/content/docs/troubleshooting/triggers.mdx
index 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 ma
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
+- **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 help
diff --git a/docs/public/images/troubleshooting/troubleshooting-auth-app-blocked.png b/docs/public/images/troubleshooting/troubleshooting-auth-app-blocked.png
new file mode 100644
index 000000000..096e8b14b
Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-auth-app-blocked.png differ
diff --git a/docs/public/images/troubleshooting/troubleshooting-auth-config-id.png b/docs/public/images/troubleshooting/troubleshooting-auth-config-id.png
new file mode 100644
index 000000000..7610fa982
Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-auth-config-id.png differ
diff --git a/docs/public/images/troubleshooting/troubleshooting-dashboard-rename-error.jpg b/docs/public/images/troubleshooting/troubleshooting-dashboard-rename-error.jpg
new file mode 100644
index 000000000..6cee079e3
Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-dashboard-rename-error.jpg differ
diff --git a/docs/public/images/troubleshooting/troubleshooting-dashboard-request-id.png b/docs/public/images/troubleshooting/troubleshooting-dashboard-request-id.png
new file mode 100644
index 000000000..536ddae1f
Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-dashboard-request-id.png differ
diff --git a/docs/public/images/troubleshooting/troubleshooting-dashboard-ui-error.png b/docs/public/images/troubleshooting/troubleshooting-dashboard-ui-error.png
new file mode 100644
index 000000000..10a020816
Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-dashboard-ui-error.png differ
diff --git a/docs/public/images/troubleshooting/troubleshooting-enable-request-id-api.png b/docs/public/images/troubleshooting/troubleshooting-enable-request-id-api.png
new file mode 100644
index 000000000..3ea065f7d
Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-enable-request-id-api.png differ
diff --git a/docs/public/images/troubleshooting/troubleshooting-mcp-connected-account-id.png b/docs/public/images/troubleshooting/troubleshooting-mcp-connected-account-id.png
new file mode 100644
index 000000000..cf9abc1ce
Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-mcp-connected-account-id.png differ
diff --git a/docs/public/images/troubleshooting/troubleshooting-mcp-server-url.png b/docs/public/images/troubleshooting/troubleshooting-mcp-server-url.png
new file mode 100644
index 000000000..5216160d1
Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-mcp-server-url.png differ
diff --git a/docs/public/images/troubleshooting/troubleshooting-sdk-py-request-id.png b/docs/public/images/troubleshooting/troubleshooting-sdk-py-request-id.png
new file mode 100644
index 000000000..ae3b388d3
Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-sdk-py-request-id.png differ
diff --git a/docs/public/images/troubleshooting/troubleshooting-sdk-ts-request-id.png b/docs/public/images/troubleshooting/troubleshooting-sdk-ts-request-id.png
new file mode 100644
index 000000000..19751fa5f
Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-sdk-ts-request-id.png differ
diff --git a/docs/public/images/troubleshooting/troubleshooting-tool-log-id.png b/docs/public/images/troubleshooting/troubleshooting-tool-log-id.png
new file mode 100644
index 000000000..e49d95287
Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-tool-log-id.png differ
diff --git a/docs/public/images/troubleshooting/troubleshooting-trigger-id.png b/docs/public/images/troubleshooting/troubleshooting-trigger-id.png
new file mode 100644
index 000000000..9f94c5632
Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-trigger-id.png differ