@devries-cameron20 / composio Mirror · read-only / commits / 7815b16f3
Fork 0

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