Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 22, 12:00 UTC
update(docs): update troubleshooting guide
Uday-sidagana committed
Jan 28, 2026 at 22:23 UTC
7815b16f3fbe49a4ff7c27cbc0b345d306768c27
20 files changed
+131
-18
docs/content/docs/troubleshooting/api.mdx
+21
-1
@@ -9,7 +9,27 @@ When reporting API issues to support, provide the following:
9
10
- **cURL command**: Include the exact cURL to reproduce the issue
11
- **Request ID**: Add `x-request-id: <uuid>` header to your request and share the UUID (generate at [uuidgenerator.net](https://www.uuidgenerator.net/))
12
-- **Error details**: Share the complete error message
12
+
13
+ <img
14
+ src="/images/troubleshooting/troubleshooting-enable-request-id-api.png"
15
+ alt="Example of `x-request-id` header"
16
+ style={{ maxWidth: '800px', width: '100%', marginTop: '12px', marginLeft: '0.5rem', borderRadius: '8px', display: 'block' }}
17
+ />
18
+
19
+- **Error details**: Share the complete error message. For example:
20
+
21
+ ```json
22
+ {
23
+ "error": {
24
+ "message": "Validation error while processing request",
25
+ "error_code": 10400,
26
+ "suggested_fix": "Please check the payload.",
27
+ "errors": [
28
+ "Error in payload.text.arguments: Only one of 'text' or 'arguments' must be provided"
29
+ ]
30
+ }
31
+ }
32
+ ```
33
- **Reproduction steps**: Include any steps needed to reproduce the issue
34
35
## Getting help
docs/content/docs/troubleshooting/authentication.mdx
+16
-3
@@ -32,9 +32,22 @@ For setup guides by toolkit: [OAuth Configuration Guides](https://composio.dev/o
32
33
When reporting to support, provide:
34
35
-- **Error message**: Complete error details and screenshots
36
-- **Auth config ID**: The `authConfigId` being used
37
-- **Connected account ID**: If a connection was already created
35
+- **Error message**: Complete error details and screenshots. For example:
36
+
37
+ <img
38
+ src="/images/troubleshooting/troubleshooting-auth-app-blocked.png"
39
+ alt="Example: This app is blocked error screen shown by Google when un-verified sensitive scopes are configured"
40
+ style={{ maxWidth: '640px', width: '100%', marginTop: '12px', marginLeft: '0.5rem', borderRadius: '8px', display: 'block' }}
41
+ />
42
+
43
+- **Auth config and account IDs**: Include the `authConfigId` used for the request and, if a connection already exists, the `connected_account_id`
44
+
45
+ <img
46
+ src="/images/troubleshooting/troubleshooting-auth-config-id.png"
47
+ alt="Finding authConfigId and connected account ID in the Composio dashboard"
48
+ style={{ maxWidth: '900px', width: '100%', marginTop: '12px', marginLeft: '0.5rem', borderRadius: '8px', display: 'block' }}
49
+ />
50
+
51
- **OAuth provider**: Which service you're trying to connect
52
53
## Getting help
docs/content/docs/troubleshooting/dashboard.mdx
+22
-2
@@ -8,11 +8,31 @@ description: Troubleshooting dashboard issues
8
When reporting dashboard issues to support, provide:
9
10
- **Screenshot or recording**: Visual evidence of the issue
11
-- **Error details**: Complete error message shown in the UI
11
+- **Error details**: Complete error message shown in the UI. For example:
12
+
13
+ <img
14
+ src="/images/troubleshooting/troubleshooting-dashboard-ui-error.png"
15
+ alt="Example dashboard UI error: A project with this name already exists"
16
+ style={{ maxWidth: '640px', width: '100%', marginTop: '12px', marginLeft: '0.5rem', borderRadius: '8px', display: 'block' }}
17
+ />
18
+
19
- **Network logs**: Check browser DevTools for failing API calls and share:
20
- Error message
21
- Request ID (`x-request-id` header)
15
- - Failed endpoint URL
22
+
23
+ <img
24
+ src="/images/troubleshooting/troubleshooting-dashboard-request-id.png"
25
+ alt="Tool call error"
26
+ style={{ maxWidth: '720px', width: '100%', marginTop: '12px', marginLeft: '0.5rem', borderRadius: '8px', display: 'block' }}
27
+ />
28
+
29
+ - Failed endpoint URL (`https://backend.composio.dev/api/v3/org/project/new`)
30
+
31
+ <img
32
+ src="/images/troubleshooting/troubleshooting-dashboard-rename-error.jpg"
33
+ alt="Example network log and dashboard error for a failed tool call"
34
+ style={{ maxWidth: '720px', width: '100%', marginTop: '12px', marginLeft: '0.5rem', borderRadius: '8px', display: 'block' }}
35
+ />
36
37
## Getting help
38
docs/content/docs/troubleshooting/index.mdx
+5
-2
@@ -3,7 +3,7 @@ title: Troubleshooting
3
description: Common issues and quick links
4
---
5
6
-import { Bug, Brain, Sparkles, MessageCircle, MessageSquare, BookOpen } from 'lucide-react';
6
+import { Bug, Brain, Sparkles, MessageCircle, MessageSquare, BookOpen, Mail } from 'lucide-react';
7
8
This section is designed to help you quickly identify and resolve common issues encountered with Composio.
9
@@ -23,7 +23,10 @@ Some quick links:
23
Join our GitHub discussions to get help from the community
24
</Card>
25
<Card title="Discord community" href="https://discord.com/channels/1170785031560646836/1268871288156323901" icon={<MessageSquare />}>
26
- Post support queries on our discord channel or reach out to support@composio.dev
26
+ Post support queries on our discord channel
27
+ </Card>
28
+ <Card title="Contact Support" href="mailto:support@composio.dev" icon={<Mail />}>
29
+ Reach out to support for account, billing, or escalations
30
</Card>
31
<Card title="Migration guides" href="/docs/migration-guide" icon={<BookOpen />}>
32
Check out our migration guides to help you upgrade to the latest version.
docs/content/docs/troubleshooting/mcp.mdx
+14
-2
@@ -13,7 +13,7 @@ This error occurs when MCP cannot find a valid connected account for authenticat
13
- Account status is `ACTIVE` (not deleted)
14
- Account belongs to the same auth config used to create the MCP server
15
16
-Learn more: [Single Toolkit MCP](/docs/single-toolkit-mcp)
16
+Learn more: [MCP Developer Guide](/docs/mcp-developers#client-applications-connect-to-the-server)
17
18
## Getting 404 errors
19
@@ -37,9 +37,21 @@ This helps identify whether the issue is with your MCP client or the server.
37
When reporting to support, provide:
38
39
- **Error message**: Complete error details
40
-- **MCP server URL**: The exact URL you're connecting to
40
+- **MCP server URL**: The exact URL you're connecting to and the corresponding `mcp_server_id`
41
+
42
+ <img
43
+ src="/images/troubleshooting/troubleshooting-mcp-server-url.png"
44
+ alt="Example MCP server URL shown in the Composio dashboard"
45
+ style={{ maxWidth: '720px', width: '100%', marginTop: '12px', marginLeft: '0.5rem', borderRadius: '8px', display: 'block' }}
46
+ />
47
- **Testing results**: Whether issue reproduces in MCP Inspector/Postman or only in specific client
48
- **Connected account ID**: If facing connection issues
49
+
50
+ <img
51
+ src="/images/troubleshooting/troubleshooting-mcp-connected-account-id.png"
52
+ alt="Example connected account ID used for MCP authentication"
53
+ style={{ maxWidth: '720px', width: '100%', marginTop: '12px', marginLeft: '0.5rem', borderRadius: '8px', display: 'block' }}
54
+ />
55
- **Reproduction steps**: Clear steps to reproduce the issue
56
57
## Getting help
docs/content/docs/troubleshooting/sdks.mdx
+19
-1
@@ -5,7 +5,7 @@ description: Troubleshooting SDK issues
5
6
## Debug network issues
7
8
-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.
8
+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`.
9
10
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
11
<Tab value="Python">
@@ -22,6 +22,24 @@ COMPOSIO_LOG_LEVEL=debug
22
</Tab>
23
</Tabs>
24
25
+Once debug logging is enabled, you can find the `x-request-id` in your SDK logs:
26
+
27
+- **Python SDK example**
28
+
29
+ <img
30
+ src="/images/troubleshooting/troubleshooting-sdk-py-request-id.png"
31
+ alt="Example of x-request-id highlighted in Python SDK debug logs"
32
+ style={{ maxWidth: '720px', width: '100%', marginTop: '12px', marginLeft: '0.5rem', borderRadius: '8px', display: 'block' }}
33
+ />
34
+
35
+- **TypeScript SDK example**
36
+
37
+ <img
38
+ src="/images/troubleshooting/troubleshooting-sdk-ts-request-id.png"
39
+ alt="Example of x-request-id highlighted in TypeScript SDK debug logs"
40
+ style={{ maxWidth: '720px', width: '100%', marginTop: '12px', marginLeft: '0.5rem', borderRadius: '8px', display: 'block' }}
41
+ />
42
+
43
## Check SDK version
44
45
Ensure you're using the latest version:
docs/content/docs/troubleshooting/tools.mdx
+25
-4
@@ -41,10 +41,31 @@ Verify the connected account has necessary permissions:
41
42
When reporting to support, provide:
43
44
-- **Error message**: Complete error details
45
-- **Log ID**: From the error response
46
-- **Tool name**: Exact tool slug being executed
47
-- **Connected account ID**: Account used for execution
44
+
45
+- **Error message**: Complete error details. For example:
46
+
47
+ ```json
48
+ {
49
+ "data": {
50
+ "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",
51
+ "status_code": 404
52
+ },
53
+ "successful": false,
54
+ "error": "404 Client Error: Not Found for url: https://gmail.googleapis.com/gmail/v1/users/me/messages/123456?format=full",
55
+ "log_id": "log_tVqomBgg11-t"
56
+ }
57
+ ```
58
+
59
+- **Log ID**: From the error response.
60
+
61
+ <img
62
+ src="/images/troubleshooting/troubleshooting-tool-log-id.png"
63
+ alt="Example tool execution log showing log_id in the Composio dashboard"
64
+ style={{ maxWidth: '720px', width: '100%', marginTop: '12px', marginLeft: '0.5rem', borderRadius: '8px', display: 'block' }}
65
+ />
66
+
67
+- **Tool name**: Exact tool slug being executed (for example, `GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID`)
68
+- **Connected account ID**: Account used for execution (for example, `ca_xxx`)
69
70
## Getting help
71
docs/content/docs/troubleshooting/triggers.mdx
+9
-3
@@ -23,9 +23,15 @@ Even if the action occurred (email received, Jira issue created, etc.), there ma
23
When reporting to support, provide:
24
25
- **Error message**: Complete error details
26
-- **Connected account**: The account ID used for creating the trigger
27
-- **cURL command**: To reproduce the issue
28
-- **Reproduction steps**: Any additional steps needed
26
+- **Connected account and trigger IDs**: The connected account ID used for creating the trigger and the specific trigger ID that's failing
27
+
28
+ <img
29
+ src="/images/troubleshooting/troubleshooting-trigger-id.png"
30
+ alt="Example of trigger ID and connected account ID in the Composio dashboard"
31
+ style={{ maxWidth: '720px', width: '100%', marginTop: '12px', marginLeft: '0.5rem', borderRadius: '8px', display: 'block' }}
32
+ />
33
+
34
+- **Reproduction steps**: Clear, step-by-step instructions to reproduce the issue, including key trigger configuration details (for example, the `interval`)
35
36
## Getting help
37
docs/public/images/troubleshooting/troubleshooting-auth-app-blocked.png
Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-auth-app-blocked.png differ
docs/public/images/troubleshooting/troubleshooting-auth-config-id.png
Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-auth-config-id.png differ
docs/public/images/troubleshooting/troubleshooting-dashboard-rename-error.jpg
Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-dashboard-rename-error.jpg differ
docs/public/images/troubleshooting/troubleshooting-dashboard-request-id.png
Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-dashboard-request-id.png differ
docs/public/images/troubleshooting/troubleshooting-dashboard-ui-error.png
Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-dashboard-ui-error.png differ
docs/public/images/troubleshooting/troubleshooting-enable-request-id-api.png
Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-enable-request-id-api.png differ
docs/public/images/troubleshooting/troubleshooting-mcp-connected-account-id.png
Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-mcp-connected-account-id.png differ
docs/public/images/troubleshooting/troubleshooting-mcp-server-url.png
Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-mcp-server-url.png differ
docs/public/images/troubleshooting/troubleshooting-sdk-py-request-id.png
Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-sdk-py-request-id.png differ
docs/public/images/troubleshooting/troubleshooting-sdk-ts-request-id.png
Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-sdk-ts-request-id.png differ
docs/public/images/troubleshooting/troubleshooting-tool-log-id.png
Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-tool-log-id.png differ
docs/public/images/troubleshooting/troubleshooting-trigger-id.png
Binary files /dev/null and b/docs/public/images/troubleshooting/troubleshooting-trigger-id.png differ