@devries-cameron20 / composio Mirror · read-only / commits / fd169d7fa
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, 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