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, 19:30 UTC
Docs: Add troubleshooting section (#2022)
Co-authored-by: Soham <sohamganatra1@gmail.com>
Sushmitha Mallesh committed
Oct 3, 2025 at 05:38 UTC
fd169d7faa56cf500019437c4816ff11aaf13640
9 files changed
+366
fern/docs.yml
+27
@@ -190,6 +190,33 @@ navigation:
190
- page: Migration Guide
191
path: pages/dist/migration-guide.mdx
192
slug: migration
193
+ - section: Troubleshooting
194
+ slug: troubleshooting
195
+ contents:
196
+ - page: Overview
197
+ path: pages/src/troubleshooting/overview.mdx
198
+ slug: overview
199
+ - page: API
200
+ path: pages/src/troubleshooting/api.mdx
201
+ slug: api
202
+ - page: Authentication
203
+ path: pages/src/troubleshooting/authentication.mdx
204
+ slug: authentication
205
+ - page: Dashboard
206
+ path: pages/src/troubleshooting/dashboard.mdx
207
+ slug: dashboard
208
+ - page: MCP
209
+ path: pages/src/troubleshooting/mcp.mdx
210
+ slug: mcp
211
+ - page: SDKs
212
+ path: pages/src/troubleshooting/sdks.mdx
213
+ slug: sdks
214
+ - page: Tools & Toolkits
215
+ path: pages/src/troubleshooting/tools.mdx
216
+ slug: tools
217
+ - page: Triggers
218
+ path: pages/src/troubleshooting/triggers.mdx
219
+ slug: triggers
220
- tab: examples
221
layout:
222
- section: Getting Started
fern/pages/src/troubleshooting/api.mdx
new
+21
@@ -0,0 +1,21 @@
1
+---
2
+title: API
3
+subtitle: Debugging and troubleshooting API issues
4
+image: "https://og.composio.dev/api/og?title=API%20Troubleshooting"
5
+keywords: 'api, rest, troubleshooting, curl, debugging'
6
+hide-nav-links: true
7
+---
8
+
9
+## Reporting API issues
10
+
11
+When reporting API issues to support, provide the following:
12
+
13
+- **cURL command**: Include the exact cURL to reproduce the issue
14
+- **Request ID**: Add `x-request-id: <uuid>` header to your request and share the UUID (generate at [uuidgenerator.net](https://www.uuidgenerator.net/))
15
+- **Error details**: Share the complete error message
16
+- **Reproduction steps**: Include any steps needed to reproduce the issue
17
+
18
+## Getting help
19
+
20
+- **Email**: support@composio.dev
21
+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)
\ No newline at end of file
fern/pages/src/troubleshooting/authentication.mdx
new
+45
@@ -0,0 +1,45 @@
1
+---
2
+title: Authentication
3
+subtitle: Debugging and troubleshooting authentication issues
4
+image: "https://og.composio.dev/api/og?title=Authentication%20Troubleshooting"
5
+keywords: 'authentication, oauth, connections, scopes, troubleshooting'
6
+hide-nav-links: true
7
+---
8
+
9
+## Using Composio's default OAuth app
10
+
11
+When using our default OAuth configuration:
12
+
13
+- **Don't add additional scopes** - They may not be approved in our OAuth app
14
+- Use only the pre-configured scopes provided
15
+
16
+## Using custom OAuth apps
17
+
18
+Ensure your OAuth app is configured correctly:
19
+
20
+- **Redirect URL**: Must match exactly what's configured in your OAuth provider
21
+- **Scopes**: Auth config scopes must match your OAuth app configuration
22
+- **Credentials**: Verify client ID and secret are correct
23
+
24
+For setup guides by toolkit: [OAuth Configuration Guides](https://composio.dev/oauth)
25
+
26
+## Common authentication issues
27
+
28
+- **Invalid redirect URI**: Check the callback URL matches exactly
29
+- **Scope mismatch**: Ensure requested scopes are configured in both auth config and OAuth app
30
+- **Expired tokens**: Try refreshing the connection
31
+- **Rate limits**: Some providers limit authentication attempts
32
+
33
+## Reporting authentication issues
34
+
35
+When reporting to support, provide:
36
+
37
+- **Error message**: Complete error details and screenshots
38
+- **Auth config ID**: The `authConfigId` being used
39
+- **Connected account ID**: If a connection was already created
40
+- **OAuth provider**: Which service you're trying to connect
41
+
42
+## Getting help
43
+
44
+- **Email**: support@composio.dev
45
+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)
\ No newline at end of file
fern/pages/src/troubleshooting/dashboard.mdx
new
+23
@@ -0,0 +1,23 @@
1
+---
2
+title: Dashboard
3
+subtitle: Debugging and troubleshooting dashboard issues
4
+image: "https://og.composio.dev/api/og?title=Dashboard%20Troubleshooting"
5
+keywords: 'dashboard, platform, UI, troubleshooting, debugging'
6
+hide-nav-links: true
7
+---
8
+
9
+## Reporting dashboard issues
10
+
11
+When reporting dashboard issues to support, provide:
12
+
13
+- **Screenshot or recording**: Visual evidence of the issue
14
+- **Error details**: Complete error message shown in the UI
15
+- **Network logs**: Check browser DevTools for failing API calls and share:
16
+ - Error message
17
+ - Request ID (`x-request-id` header)
18
+ - Failed endpoint URL
19
+
20
+## Getting help
21
+
22
+- **Email**: support@composio.dev
23
+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)
\ No newline at end of file
fern/pages/src/troubleshooting/mcp.mdx
new
+51
@@ -0,0 +1,51 @@
1
+---
2
+title: MCP
3
+subtitle: Debugging and troubleshooting MCP server issues
4
+image: "https://og.composio.dev/api/og?title=MCP%20Troubleshooting"
5
+keywords: 'mcp, model context protocol, server, troubleshooting, debugging'
6
+hide-nav-links: true
7
+---
8
+
9
+## Connected account not found error
10
+
11
+This error occurs when MCP cannot find a valid connected account for authentication:
12
+
13
+- **Specify an account**: Provide either `connected_account_id` or `user_id` in your MCP configuration
14
+- **Default behavior**: Without specification, MCP uses `user_id=default`. If multiple connections exist with the same user_id, the most recent is used
15
+- **Verification checklist**:
16
+ - Account status is `ACTIVE` (not deleted)
17
+ - Account belongs to the same auth config used to create the MCP server
18
+
19
+Learn more: [MCP Developer Guide](/docs/mcp-developers#client-applications-connect-to-the-server)
20
+
21
+## Getting 404 errors
22
+
23
+Verify your URL format matches one of these patterns:
24
+
25
+- `https://mcp.composio.dev/composio/server/<UUID>/mcp`
26
+- `https://apollo-<randomID>-composio.vercel.app/v3/mcp/<UUID>`
27
+- `https://apollo.composio.dev/v3/mcp/<UUID>`
28
+
29
+## Testing and debugging
30
+
31
+If experiencing issues, test your MCP server with:
32
+
33
+- [Postman MCP Requests](https://learning.postman.com/docs/postman-ai-developer-tools/mcp-requests/create/)
34
+- [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector)
35
+
36
+This helps identify whether the issue is with your MCP client or the server.
37
+
38
+## Reporting MCP issues
39
+
40
+When reporting to support, provide:
41
+
42
+- **Error message**: Complete error details
43
+- **MCP server URL**: The exact URL you're connecting to
44
+- **Testing results**: Whether issue reproduces in MCP Inspector/Postman or only in specific client
45
+- **Connected account ID**: If facing connection issues
46
+- **Reproduction steps**: Clear steps to reproduce the issue
47
+
48
+## Getting help
49
+
50
+- **Email**: support@composio.dev
51
+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)
\ No newline at end of file
fern/pages/src/troubleshooting/overview.mdx
new
+58
@@ -0,0 +1,58 @@
1
+---
2
+title: Troubleshooting
3
+subtitle: Common issues and quick links
4
+image: "https://og.composio.dev/api/og?title=Troubleshooting"
5
+keywords: 'troubleshooting, errors, issues, debugging, problems'
6
+hide-nav-links: true
7
+---
8
+
9
+This section is designed to help you quickly identify and resolve common issues encountered with the Composio.
10
+
11
+Some quick links:
12
+<Card
13
+ title="Report issues"
14
+ icon="fa-solid fa-bug"
15
+ href="https://github.com/ComposioHQ/composio/issues/new?labels=bug"
16
+>
17
+ Found a bug? Please create a Github issue!
18
+</Card>
19
+
20
+<Card
21
+ title="Ask AI"
22
+ icon="fa-solid fa-brain"
23
+ href="https://deepwiki.com/ComposioHQ/composio"
24
+>
25
+ Try to use Ask AI in the docs or deepwiki to get the fastes responses on features, types, and best practices.
26
+</Card>
27
+
28
+<Card
29
+ title="Feature requests"
30
+ icon="fa-solid fa-sparkles"
31
+ href="https://github.com/ComposioHQ/composio/issues/new?labels=enhancement"
32
+>
33
+ Have an idea for improving Composio? Share your feature suggestions with us and we will prioritise your requests
34
+</Card>
35
+
36
+<Card
37
+ title="Ask the community"
38
+ icon="fa-solid fa-comments"
39
+ href="https://github.com/ComposioHQ/composio/discussions"
40
+>
41
+ Join our GitHub discussions to get help from the community
42
+</Card>
43
+
44
+<Card
45
+ title="Discord community"
46
+ icon="fa-brands fa-discord"
47
+ href="https://discord.com/channels/1170785031560646836/1268871288156323901"
48
+>
49
+ Post support queries on our discord channel or reachout to support@composio.dev
50
+</Card>
51
+
52
+<Card
53
+ title="Migration guides"
54
+ icon="fa-solid fa-book"
55
+ href="/docs/migration"
56
+>
57
+ Check out our migration guides to help you upgrade to the latest version.
58
+</Card>
\ No newline at end of file
fern/pages/src/troubleshooting/sdks.mdx
new
+50
@@ -0,0 +1,50 @@
1
+---
2
+title: SDKs
3
+subtitle: Debugging and troubleshooting SDK issues
4
+image: "https://og.composio.dev/api/og?title=SDK%20Troubleshooting"
5
+keywords: 'sdk, python, typescript, troubleshooting, debugging'
6
+hide-nav-links: true
7
+---
8
+
9
+## Debug network issues
10
+
11
+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.
12
+
13
+<CodeGroup>
14
+```python Python
15
+# Set environment variable
16
+COMPOSIO_LOGGING_LEVEL=debug
17
+```
18
+```typescript TypeScript
19
+// Set environment variable
20
+COMPOSIO_LOG_LEVEL=debug
21
+```
22
+</CodeGroup>
23
+
24
+## Check SDK version
25
+
26
+Ensure you're using the latest version:
27
+
28
+<CodeGroup>
29
+```bash Python
30
+pip install --upgrade composio
31
+```
32
+```bash TypeScript
33
+npm install @composio/core@latest
34
+```
35
+</CodeGroup>
36
+
37
+Check current version:
38
+- Python: [PyPI](https://pypi.org/project/composio/)
39
+- TypeScript: [npm](https://www.npmjs.com/package/@composio/core)
40
+
41
+## Common issues
42
+
43
+- **Type errors or parameter confusion**: Search [DeepWiki](https://deepwiki.com/ComposioHQ/composio) or use the Ask AI assistant
44
+- **Tool-specific issues**: Check the [specific tool's documentation](/toolkits)
45
+- **Bug reporting**: Create a [GitHub issue](https://github.com/ComposioHQ/composio/issues/new?labels=bug) with debug logs and reproduction steps
46
+
47
+## Getting help
48
+
49
+- **Email**: support@composio.dev
50
+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)
\ No newline at end of file
fern/pages/src/troubleshooting/tools.mdx
new
+55
@@ -0,0 +1,55 @@
1
+---
2
+title: Tools & Toolkits
3
+subtitle: Debugging and troubleshooting tool execution issues
4
+image: "https://og.composio.dev/api/og?title=Tools%20Troubleshooting"
5
+keywords: 'tools, toolkits, execution, permissions, troubleshooting'
6
+hide-nav-links: true
7
+---
8
+
9
+## Tool execution failures (401/403 errors)
10
+
11
+Authentication and permission errors typically occur due to:
12
+
13
+### Missing scopes
14
+
15
+Check if your connection has the required scopes using this API:
16
+
17
+```bash
18
+curl --location 'https://backend.composio.dev/api/v3/tools/get_scopes_required' \
19
+--header 'x-api-key: YOUR_COMPOSIO_API_KEY' \
20
+--header 'Content-Type: application/json' \
21
+--data '{
22
+ "tools": [
23
+ "SLACK_SENDS_A_MESSAGE_TO_A_SLACK_CHANNEL",
24
+ "SLACK_CREATE_A_REMINDER"
25
+ ]
26
+}'
27
+```
28
+
29
+### Insufficient permissions
30
+
31
+Verify the connected account has necessary permissions:
32
+
33
+- **Admin requirements**: Some tools require admin-level access
34
+- **Paid accounts**: Certain toolkits need paid subscriptions
35
+ - Example: MS Teams requires Microsoft 365 account + Azure AD tenant
36
+
37
+## Tool not working
38
+
39
+- Check [tool-specific documentation](/toolkits) for requirements
40
+- Verify the connected account is active and properly authenticated
41
+- Test with the latest SDK version
42
+
43
+## Reporting tool issues
44
+
45
+When reporting to support, provide:
46
+
47
+- **Error message**: Complete error details
48
+- **Log ID**: From the error response
49
+- **Tool name**: Exact tool slug being executed
50
+- **Connected account ID**: Account used for execution
51
+
52
+## Getting help
53
+
54
+- **Email**: support@composio.dev
55
+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)
\ No newline at end of file
fern/pages/src/troubleshooting/triggers.mdx
new
+36
@@ -0,0 +1,36 @@
1
+---
2
+title: Triggers
3
+subtitle: Debugging and troubleshooting trigger issues
4
+image: "https://og.composio.dev/api/og?title=Triggers%20Troubleshooting"
5
+keywords: 'triggers, webhooks, events, troubleshooting, debugging'
6
+hide-nav-links: true
7
+---
8
+
9
+## Unable to create trigger
10
+
11
+Check the error message - the account might not have sufficient permissions or required scopes.
12
+
13
+## Type errors with trigger payloads
14
+
15
+Having issues with trigger payload types? Search [DeepWiki](https://deepwiki.com/ComposioHQ/composio) or use the Ask AI assistant for type definitions and examples.
16
+
17
+## Not receiving trigger payloads
18
+
19
+Even if the action occurred (email received, Jira issue created, etc.), there may be delays:
20
+
21
+- **Gmail triggers**: Uses polling with minimum 1-minute frequency - expect delays of up to a minute
22
+- **Other services**: May have their own polling intervals or webhook delivery delays
23
+
24
+## Reporting trigger issues
25
+
26
+When reporting to support, provide:
27
+
28
+- **Error message**: Complete error details
29
+- **Connected account**: The account ID used for creating the trigger
30
+- **cURL command**: To reproduce the issue
31
+- **Reproduction steps**: Any additional steps needed
32
+
33
+## Getting help
34
+
35
+- **Email**: support@composio.dev
36
+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)
\ No newline at end of file