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.

Docs: Add troubleshooting section (#2022)

Sushmitha Malleshfd169d7faa56
diff --git a/fern/docs.yml b/fern/docs.yml
index 9ffc8cab1..b796a18b4 100644
--- a/fern/docs.yml
+++ b/fern/docs.yml
@@ -190,6 +190,33 @@ navigation:
- page: Migration Guide
path: pages/dist/migration-guide.mdx
slug: migration
+ - section: Troubleshooting
+ slug: troubleshooting
+ contents:
+ - page: Overview
+ path: pages/src/troubleshooting/overview.mdx
+ slug: overview
+ - page: API
+ path: pages/src/troubleshooting/api.mdx
+ slug: api
+ - page: Authentication
+ path: pages/src/troubleshooting/authentication.mdx
+ slug: authentication
+ - page: Dashboard
+ path: pages/src/troubleshooting/dashboard.mdx
+ slug: dashboard
+ - page: MCP
+ path: pages/src/troubleshooting/mcp.mdx
+ slug: mcp
+ - page: SDKs
+ path: pages/src/troubleshooting/sdks.mdx
+ slug: sdks
+ - page: Tools & Toolkits
+ path: pages/src/troubleshooting/tools.mdx
+ slug: tools
+ - page: Triggers
+ path: pages/src/troubleshooting/triggers.mdx
+ slug: triggers
- tab: examples
layout:
- section: Getting Started
diff --git a/fern/pages/src/troubleshooting/api.mdx b/fern/pages/src/troubleshooting/api.mdx
new file mode 100644
index 000000000..805e3ce8a
--- /dev/null
+++ b/fern/pages/src/troubleshooting/api.mdx
@@ -0,0 +1,21 @@
+---
+title: API
+subtitle: Debugging and troubleshooting API issues
+image: "https://og.composio.dev/api/og?title=API%20Troubleshooting"
+keywords: 'api, rest, troubleshooting, curl, debugging'
+hide-nav-links: true
+---
+
+## Reporting API issues
+
+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
+- **Reproduction steps**: Include any steps needed to reproduce the issue
+
+## Getting help
+
+- **Email**: [email protected]
+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)
\ No newline at end of file
diff --git a/fern/pages/src/troubleshooting/authentication.mdx b/fern/pages/src/troubleshooting/authentication.mdx
new file mode 100644
index 000000000..30204cf18
--- /dev/null
+++ b/fern/pages/src/troubleshooting/authentication.mdx
@@ -0,0 +1,45 @@
+---
+title: Authentication
+subtitle: Debugging and troubleshooting authentication issues
+image: "https://og.composio.dev/api/og?title=Authentication%20Troubleshooting"
+keywords: 'authentication, oauth, connections, scopes, troubleshooting'
+hide-nav-links: true
+---
+
+## Using Composio's default OAuth app
+
+When using our default OAuth configuration:
+
+- **Don't add additional scopes** - They may not be approved in our OAuth app
+- Use only the pre-configured scopes provided
+
+## Using custom OAuth apps
+
+Ensure your OAuth app is configured correctly:
+
+- **Redirect URL**: Must match exactly what's configured in your OAuth provider
+- **Scopes**: Auth config scopes must match your OAuth app configuration
+- **Credentials**: Verify client ID and secret are correct
+
+For setup guides by toolkit: [OAuth Configuration Guides](https://composio.dev/oauth)
+
+## Common authentication issues
+
+- **Invalid redirect URI**: Check the callback URL matches exactly
+- **Scope mismatch**: Ensure requested scopes are configured in both auth config and OAuth app
+- **Expired tokens**: Try refreshing the connection
+- **Rate limits**: Some providers limit authentication attempts
+
+## Reporting authentication issues
+
+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
+- **OAuth provider**: Which service you're trying to connect
+
+## Getting help
+
+- **Email**: [email protected]
+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)
\ No newline at end of file
diff --git a/fern/pages/src/troubleshooting/dashboard.mdx b/fern/pages/src/troubleshooting/dashboard.mdx
new file mode 100644
index 000000000..89736794c
--- /dev/null
+++ b/fern/pages/src/troubleshooting/dashboard.mdx
@@ -0,0 +1,23 @@
+---
+title: Dashboard
+subtitle: Debugging and troubleshooting dashboard issues
+image: "https://og.composio.dev/api/og?title=Dashboard%20Troubleshooting"
+keywords: 'dashboard, platform, UI, troubleshooting, debugging'
+hide-nav-links: true
+---
+
+## Reporting 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
+- **Network logs**: Check browser DevTools for failing API calls and share:
+ - Error message
+ - Request ID (`x-request-id` header)
+ - Failed endpoint URL
+
+## Getting help
+
+- **Email**: [email protected]
+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)
\ No newline at end of file
diff --git a/fern/pages/src/troubleshooting/mcp.mdx b/fern/pages/src/troubleshooting/mcp.mdx
new file mode 100644
index 000000000..029f73c13
--- /dev/null
+++ b/fern/pages/src/troubleshooting/mcp.mdx
@@ -0,0 +1,51 @@
+---
+title: MCP
+subtitle: Debugging and troubleshooting MCP server issues
+image: "https://og.composio.dev/api/og?title=MCP%20Troubleshooting"
+keywords: 'mcp, model context protocol, server, troubleshooting, debugging'
+hide-nav-links: true
+---
+
+## Connected account not found error
+
+This error occurs when MCP cannot find a valid connected account for authentication:
+
+- **Specify an account**: Provide either `connected_account_id` or `user_id` in your MCP configuration
+- **Default behavior**: Without specification, MCP uses `user_id=default`. If multiple connections exist with the same user_id, the most recent is used
+- **Verification checklist**:
+ - Account status is `ACTIVE` (not deleted)
+ - Account belongs to the same auth config used to create the MCP server
+
+Learn more: [MCP Developer Guide](/docs/mcp-developers#client-applications-connect-to-the-server)
+
+## Getting 404 errors
+
+Verify your URL format matches one of these patterns:
+
+- `https://mcp.composio.dev/composio/server/<UUID>/mcp`
+- `https://apollo-<randomID>-composio.vercel.app/v3/mcp/<UUID>`
+- `https://apollo.composio.dev/v3/mcp/<UUID>`
+
+## Testing and debugging
+
+If experiencing issues, test your MCP server with:
+
+- [Postman MCP Requests](https://learning.postman.com/docs/postman-ai-developer-tools/mcp-requests/create/)
+- [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector)
+
+This helps identify whether the issue is with your MCP client or the server.
+
+## Reporting MCP issues
+
+When reporting to support, provide:
+
+- **Error message**: Complete error details
+- **MCP server URL**: The exact URL you're connecting to
+- **Testing results**: Whether issue reproduces in MCP Inspector/Postman or only in specific client
+- **Connected account ID**: If facing connection issues
+- **Reproduction steps**: Clear steps to reproduce the issue
+
+## Getting help
+
+- **Email**: [email protected]
+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)
\ No newline at end of file
diff --git a/fern/pages/src/troubleshooting/overview.mdx b/fern/pages/src/troubleshooting/overview.mdx
new file mode 100644
index 000000000..ea9faa33a
--- /dev/null
+++ b/fern/pages/src/troubleshooting/overview.mdx
@@ -0,0 +1,58 @@
+---
+title: Troubleshooting
+subtitle: Common issues and quick links
+image: "https://og.composio.dev/api/og?title=Troubleshooting"
+keywords: 'troubleshooting, errors, issues, debugging, problems'
+hide-nav-links: true
+---
+
+This section is designed to help you quickly identify and resolve common issues encountered with the Composio.
+
+Some quick links:
+<Card
+ title="Report issues"
+ icon="fa-solid fa-bug"
+ href="https://github.com/ComposioHQ/composio/issues/new?labels=bug"
+>
+ Found a bug? Please create a Github issue!
+</Card>
+
+<Card
+ title="Ask AI"
+ icon="fa-solid fa-brain"
+ href="https://deepwiki.com/ComposioHQ/composio"
+>
+ Try to use Ask AI in the docs or deepwiki to get the fastes responses on features, types, and best practices.
+</Card>
+
+<Card
+ title="Feature requests"
+ icon="fa-solid fa-sparkles"
+ href="https://github.com/ComposioHQ/composio/issues/new?labels=enhancement"
+>
+ Have an idea for improving Composio? Share your feature suggestions with us and we will prioritise your requests
+</Card>
+
+<Card
+ title="Ask the community"
+ icon="fa-solid fa-comments"
+ href="https://github.com/ComposioHQ/composio/discussions"
+>
+ Join our GitHub discussions to get help from the community
+</Card>
+
+<Card
+ title="Discord community"
+ icon="fa-brands fa-discord"
+ href="https://discord.com/channels/1170785031560646836/1268871288156323901"
+>
+ Post support queries on our discord channel or reachout to [email protected]
+</Card>
+
+<Card
+ title="Migration guides"
+ icon="fa-solid fa-book"
+ href="/docs/migration"
+>
+ Check out our migration guides to help you upgrade to the latest version.
+</Card>
\ No newline at end of file
diff --git a/fern/pages/src/troubleshooting/sdks.mdx b/fern/pages/src/troubleshooting/sdks.mdx
new file mode 100644
index 000000000..d92dabf4e
--- /dev/null
+++ b/fern/pages/src/troubleshooting/sdks.mdx
@@ -0,0 +1,50 @@
+---
+title: SDKs
+subtitle: Debugging and troubleshooting SDK issues
+image: "https://og.composio.dev/api/og?title=SDK%20Troubleshooting"
+keywords: 'sdk, python, typescript, troubleshooting, debugging'
+hide-nav-links: true
+---
+
+## Debug network issues
+
+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.
+
+<CodeGroup>
+```python Python
+# Set environment variable
+COMPOSIO_LOGGING_LEVEL=debug
+```
+```typescript TypeScript
+// Set environment variable
+COMPOSIO_LOG_LEVEL=debug
+```
+</CodeGroup>
+
+## Check SDK version
+
+Ensure you're using the latest version:
+
+<CodeGroup>
+```bash Python
+pip install --upgrade composio
+```
+```bash TypeScript
+npm install @composio/core@latest
+```
+</CodeGroup>
+
+Check current version:
+- Python: [PyPI](https://pypi.org/project/composio/)
+- TypeScript: [npm](https://www.npmjs.com/package/@composio/core)
+
+## Common issues
+
+- **Type errors or parameter confusion**: Search [DeepWiki](https://deepwiki.com/ComposioHQ/composio) or use the Ask AI assistant
+- **Tool-specific issues**: Check the [specific tool's documentation](/toolkits)
+- **Bug reporting**: Create a [GitHub issue](https://github.com/ComposioHQ/composio/issues/new?labels=bug) with debug logs and reproduction steps
+
+## Getting help
+
+- **Email**: [email protected]
+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)
\ No newline at end of file
diff --git a/fern/pages/src/troubleshooting/tools.mdx b/fern/pages/src/troubleshooting/tools.mdx
new file mode 100644
index 000000000..7e7dc6011
--- /dev/null
+++ b/fern/pages/src/troubleshooting/tools.mdx
@@ -0,0 +1,55 @@
+---
+title: Tools & Toolkits
+subtitle: Debugging and troubleshooting tool execution issues
+image: "https://og.composio.dev/api/og?title=Tools%20Troubleshooting"
+keywords: 'tools, toolkits, execution, permissions, troubleshooting'
+hide-nav-links: true
+---
+
+## Tool execution failures (401/403 errors)
+
+Authentication and permission errors typically occur due to:
+
+### Missing scopes
+
+Check if your connection has the required scopes using this API:
+
+```bash
+curl --location 'https://backend.composio.dev/api/v3/tools/get_scopes_required' \
+--header 'x-api-key: YOUR_COMPOSIO_API_KEY' \
+--header 'Content-Type: application/json' \
+--data '{
+ "tools": [
+ "SLACK_SENDS_A_MESSAGE_TO_A_SLACK_CHANNEL",
+ "SLACK_CREATE_A_REMINDER"
+ ]
+}'
+```
+
+### Insufficient permissions
+
+Verify the connected account has necessary permissions:
+
+- **Admin requirements**: Some tools require admin-level access
+- **Paid accounts**: Certain toolkits need paid subscriptions
+ - Example: MS Teams requires Microsoft 365 account + Azure AD tenant
+
+## Tool not working
+
+- Check [tool-specific documentation](/toolkits) for requirements
+- Verify the connected account is active and properly authenticated
+- Test with the latest SDK version
+
+## Reporting tool issues
+
+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
+
+## Getting help
+
+- **Email**: [email protected]
+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)
\ No newline at end of file
diff --git a/fern/pages/src/troubleshooting/triggers.mdx b/fern/pages/src/troubleshooting/triggers.mdx
new file mode 100644
index 000000000..54f7b4758
--- /dev/null
+++ b/fern/pages/src/troubleshooting/triggers.mdx
@@ -0,0 +1,36 @@
+---
+title: Triggers
+subtitle: Debugging and troubleshooting trigger issues
+image: "https://og.composio.dev/api/og?title=Triggers%20Troubleshooting"
+keywords: 'triggers, webhooks, events, troubleshooting, debugging'
+hide-nav-links: true
+---
+
+## Unable to create trigger
+
+Check the error message - the account might not have sufficient permissions or required scopes.
+
+## Type errors with trigger payloads
+
+Having issues with trigger payload types? Search [DeepWiki](https://deepwiki.com/ComposioHQ/composio) or use the Ask AI assistant for type definitions and examples.
+
+## Not receiving trigger payloads
+
+Even if the action occurred (email received, Jira issue created, etc.), there may be delays:
+
+- **Gmail triggers**: Uses polling with minimum 1-minute frequency - expect delays of up to a minute
+- **Other services**: May have their own polling intervals or webhook delivery delays
+
+## Reporting trigger issues
+
+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
+
+## Getting help
+
+- **Email**: [email protected]
+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)
\ No newline at end of file