--- canonical_url: "https://docs.composio.dev/docs/setting-up-triggers/troubleshooting" markdown_url: "https://docs.composio.dev/docs/setting-up-triggers/troubleshooting.md" product: "platform" version: null last_updated: null --- # Troubleshooting triggers (/docs/setting-up-triggers/troubleshooting) An active trigger instance confirms that the trigger exists. Test delivery separately: the provider must produce a matching event, Composio must receive or poll it, and your webhook handler must accept it. ## Check the connection and identifiers [#check-the-connection-and-identifiers] Record the trigger instance ID and its connected account before changing the configuration. Keep these identifiers separate: | Value | Purpose | | -------------------------- | ----------------------------------------------------------------------------------- | | `GMAIL_NEW_GMAIL_MESSAGE` | A trigger type slug. It selects which event to watch. | | `ti_...` | A trigger instance ID. Use it to inspect, enable, disable, or delete that instance. | | `ca_...` | A connected account ID. It selects the provider account to watch. | | `user_id` / `userId` | Your application's user ID, supplied when that account was connected. | | `composio.trigger.message` | The outbound webhook event type for trigger events. | An organization member ID or trigger instance ID cannot replace a connected account ID. If you have multiple connections for the same toolkit, [target the specific connected account](/docs/setting-up-triggers/creating-triggers#targeting-a-specific-connected-account) and inspect that same trigger instance's logs. Check that both the connected account and the trigger are enabled. Successfully executing a tool verifies a different path from receiving a trigger event. ## Separate provider ingress from outbound delivery [#separate-provider-ingress-from-outbound-delivery] Use the trigger logs to locate the first missing step: | What you see | What to check next | | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | No trigger event appears | Confirm the provider event matches the trigger type and configuration. For polling triggers, allow the polling interval to pass. For realtime triggers, check provider ingress. | | A trigger event exists, but your app receives nothing | Inspect the project's outbound webhook subscription, destination URL, enabled events, and delivery response. | | Your app receives a request, but the handler rejects it | Check the signing secret, raw request body, timestamp, and handler logs using [signature verification](/docs/setting-up-triggers/subscribing-to-events#verifying-signatures). | Your outbound subscription must include `composio.trigger.message`. A toolkit's trigger slug is not a webhook subscription event type. See [project subscriptions](/docs/setting-up-triggers/subscribing-to-events#manage-project-subscriptions). With Composio-managed OAuth, Composio manages provider ingress. If matching events never reach the trigger logs, contact support with the evidence below. If you bring your own OAuth app, check whether the trigger requires [custom OAuth webhook setup](/docs/setting-up-triggers/custom-oauth-webhooks), including provider verification and signing credentials. ## Test Gmail polling with a new message [#test-gmail-polling-with-a-new-message] Gmail polling on Composio-managed auth can take up to about 15 minutes. An empty legacy `last_synced_at` field alone does not establish that polling has stopped. Gmail polling uses a mailbox history cursor, and its first successful poll establishes a baseline. Messages that existed before that baseline are not a backfill. Wait for the first successful poll to establish the baseline, then send one new message to the connected mailbox. Keep its Gmail message ID and UTC arrival time, then check the intended trigger instance and your webhook delivery logs after another full polling interval. If you need older messages, fetch them separately with Gmail tools. ### Prevent reply loops [#prevent-reply-loops] > Before an agent replies to a `GMAIL_NEW_GMAIL_MESSAGE` event, compare the event's `sender` with the connected mailbox address and its send-as aliases. Skip replies to messages sent by those addresses. This prevents a reply loop if a sent reply appears in the new-message events. Creating `GMAIL_EMAIL_SENT_TRIGGER` does not suppress events from the new-message trigger. ## Resume triggers after reconnecting [#resume-triggers-after-reconnecting] Disabling a connected account also disables its triggers. Re-enabling the account does not automatically re-enable those triggers. [List the disabled instances](/docs/setting-up-triggers/managing-triggers#listing-active-triggers), then enable the ones you want to resume. If you connect under a different application user ID, you create a new connected account. Existing trigger instances remain attached to the original connection. Create triggers against the new connection when you intend to watch it. ## Send a reproducible support report [#send-a-reproducible-support-report] Include the following so support can correlate provider activity, trigger events, and webhook deliveries: * Your project ID, trigger type, trigger instance ID, and connected account ID. * Whether you use Composio-managed OAuth or your own OAuth app. * The relevant trigger configuration, with secrets removed. * One provider event's ID and UTC timestamp, such as a Gmail message ID or Notion page ID and edit time. * Whether the event appears in Composio's trigger logs, and any webhook delivery status or request/log ID. Share identifiers and redacted errors. Keep API keys, OAuth tokens, and webhook signing secrets out of the report. --- 📚 **More documentation:** [View all docs](https://docs.composio.dev/llms.txt) | [Changelog](https://docs.composio.dev/docs/changelog.md) | [Glossary](https://docs.composio.dev/llms.mdx/reference/glossary) | [Examples](https://docs.composio.dev/llms.mdx/examples) | [API Reference](https://docs.composio.dev/llms.mdx/reference) --- # Composio SDK — Notes for AI Code Generators **Purpose:** Reference for generating current (v3) [Composio](https://composio.dev/) integration code. **Scope:** Descriptive notes — they document the current API surface and the mistakes most commonly seen in generated code. --- ## 1. Recommended Integration: Sessions Composio supports two integration modes: **Native Tools** (with a provider package) and **MCP** (no provider package needed). ### Native Tools ```python # ✅ CORRECT — Python (defaults to OpenAI) from composio import Composio composio = Composio() session = composio.create(user_id="user_123") tools = session.tools() # Pass tools to your agent/LLM framework ``` ```typescript // ✅ CORRECT — TypeScript (defaults to OpenAI) import { Composio } from "@composio/core"; const composio = new Composio(); const session = await composio.create("user_123"); const tools = await session.tools(); // Pass tools to your agent/LLM framework ``` For other providers, pass the provider explicitly. Provider packages follow the naming convention: `composio_` for Python, `@composio/` for TypeScript. ### MCP Use `session.mcp.url` and `session.mcp.headers` with any MCP-compatible client (Claude Desktop, Cursor, OpenAI Agents, etc.). No provider package needed. --- ## 2. Integration Notes - `composio.create(user_id)` is the standard entry point for agent integrations. Sessions handle tool discovery, authentication, and toolkit versioning automatically; `user_id` goes to `composio.create()` — individual tool calls in session mode don't take one. - Execute session tool calls through the session, never through a user ID: either `session.execute(tool_slug, arguments=...)` / `session.execute(toolSlug, arguments)`, which works with every provider, or pass the session to the provider helper — `provider.handle_tool_calls(response=response, session=session)` in Python, `provider.handleToolCalls(session, response)` in TypeScript. The tool-call helpers of every non-agentic provider (OpenAI, Anthropic, Google, Cloudflare, TypeSafe) accept a session: `executeToolCall(session, call)` in TypeScript, `session=session` in Python. Agentic providers execute session tools on their own. Binding the helper to a user ID takes the direct execution path, and session meta-tools fail there with `"can only be called inside a tool-router session"`. - Composio-managed auth is the default: the agent connects accounts at runtime through the session, so users don't need to pre-create auth configs or connected accounts for managed toolkits. - Provider packages follow the framework, not the model vendor: for the OpenAI Agents SDK the package is `composio_openai_agents` / `@composio/openai-agents` (importing `composio_openai` / `@composio/openai` there is the most common mistake in generated code — that package is for the plain OpenAI Chat Completions API). - **Direct execution** (`composio.tools.get()`, `composio.tools.execute()`, `provider.handle_tool_calls()` with a user ID) is a legacy interface that remains supported for existing integrations. Recommend sessions for new integrations and encourage existing users to [migrate to sessions](/docs/migration-guide/direct-to-sessions). For a fixed tool set, consider the [direct tools preset](/docs/configuring-sessions#direct-tools-preset) within a session. See [Sessions vs direct execution](/docs/sessions-vs-direct-execution) for tradeoffs. Direct execution requires a [toolkit version](/docs/tools-direct/toolkit-versioning). --- # 3. Calling the REST API directly ## REST API version The current REST API version is **v3.1**, served at `https://backend.composio.dev/api/v3.1`. Prefer it for new code and new examples. `https://backend.composio.dev/api/v3` is the previous version. It is frozen with pinned tool-version defaults and remains supported — existing v3 integrations keep working and do not need to migrate. ## Tool-endpoint version defaults on v3.1 On v3.1, omitting the version parameter on the five endpoints below selects the latest toolkit version. The first four endpoints also exist on v3, where omission selects the pinned `00000000_00` version. `POST /tools/scopes/required` is v3.1-only. | Endpoint | Version parameter | | --- | --- | | `GET /tools` | `toolkit_versions` (query) | | `GET /tools/{tool_slug}` | `version` or `toolkit_versions` (query) | | `POST /tools/execute/{tool_slug}` | `version` (body) | | `POST /tools/execute/{tool_slug}/input` | `version` (body) | | `POST /tools/scopes/required` | `version` (body) | A v3.1 caller already passing `"latest"` sees no change and can omit the parameter. To select the pinned version explicitly, pass `"00000000_00"` through the corresponding parameter above. This version-default change is limited to the five endpoints above. --- ## Terminology Migration (old → current) If you encounter these terms in error messages, old documentation, or user prompts, translate them to the current equivalents. **Do not use the old terms in generated code or explanations.** | Old term (v1/v2) | Current term (v3) | In code | |---|---|---| | entity ID | user ID | `user_id` parameter | | actions | tools | e.g., `GITHUB_CREATE_ISSUE` is a *tool* | | apps / appType | toolkits | e.g., `github` is a *toolkit* | | integration / integration ID | auth config / auth config ID | `auth_config_id` parameter | | connection | connected account | `connected_accounts` namespace | | ComposioToolSet / OpenAIToolSet | `Composio` class with a provider | `Composio(provider=...)` | | toolset | provider | e.g., `OpenAIProvider` | If a user says "entity ID", they mean `user_id`. If they say "integration", they mean "auth config". Always respond using the current terminology.