ComposioHQ/composio · error · ComposioToolVersionRequiredError

ComposioToolVersionRequiredError

Error message

ComposioToolVersionRequiredError

What it means

ComposioToolVersionRequiredError is thrown by Tools.execute when the resolved toolkit version is 'latest' and dangerouslySkipVersionCheck is not set. The version resolves from body.version ?? getToolkitVersion(tool.toolkit.slug, this.toolkitVersions). The SDK refuses to execute against a floating 'latest' toolkit because tool schemas can change without notice, breaking pinned integrations.

Source

Thrown at ts/packages/core/src/models/Tools.ts:986

  }

  /**
   * @internal
   * Executes a composio tool via API without modifiers
   * @param tool - The tool to execute
   * @param body - The body of the tool execution
   * @returns The response from the tool execution
   */
  private async executeComposioTool(
    tool: Tool,
    body: ToolExecuteParams,
    requestOptions?: ComposioRequestOptions
  ): Promise<ToolExecuteResponse> {
    const toolkitVersion =
      body.version ?? getToolkitVersion(tool.toolkit?.slug ?? 'unknown', this.toolkitVersions);
    // if the version is latest and dangerouslySkipVersionCheck is not true, throw an error
    if (toolkitVersion === 'latest' && !body.dangerouslySkipVersionCheck) {
      throw new ComposioToolVersionRequiredError();
    }
    try {
      const executeBody: ComposioToolExecuteParams = {
        allow_tracing: body.allowTracing,
        connected_account_id: body.connectedAccountId,
        custom_auth_params: body.customAuthParams
          ? {
              base_url: body.customAuthParams.baseURL,
              body: body.customAuthParams.body,
              parameters: body.customAuthParams.parameters,
            }
          : undefined,
        /**
         * @deprecated The `customConnectionData` execute param is deprecated and will be
         * removed in a future release. Use `customAuthParams` instead.
         */
        custom_connection_data:
          body.customConnectionData as ComposioToolExecuteParams['custom_connection_data'],

View on GitHub (pinned to 64b1b85502)

Solutions

1. Pass an explicit version in the execute body: version: '<toolkit-version>' (from the tool's toolkit metadata or your toolkitVersions cache)
2. Ensure a concrete version for the toolkit slug is populated in the toolkitVersions map passed to the Tools model so getToolkitVersion resolves it
3. If you deliberately want floating latest, set dangerouslySkipVersionCheck: true in the execute body to acknowledge the risk

Example fix

// before
await composio.tools.execute({ tool, arguments, connectedAccountId });

// after
await composio.tools.execute({ tool, arguments, connectedAccountId, version: '14.0.0' });
// or opt out explicitly:
await composio.tools.execute({ tool, arguments, connectedAccountId, dangerouslySkipVersionCheck: true });

const version =
  body.version ?? toolkitVersions.get(tool.toolkit?.slug ?? 'unknown');
if (!version || version === 'latest') {
  // pin a known version or explicitly opt in
  body.version = '14.0.0'; // or body.dangerouslySkipVersionCheck = true;
}

const hasPinnedVersion = (t: { toolkit?: { slug?: string; version?: string } } | undefined): boolean =>
  Boolean(t?.toolkit?.version && t.toolkit.version !== 'latest');

try {
  await tools.execute(params);
} catch (e) {
  if (e instanceof ComposioToolVersionRequiredError) {
    // fetch toolkit version, retry with body.version pinned
  }
}

When it happens

Trigger: Calling tools.execute(...) where body.version is omitted (or literally 'latest') AND no concrete version for that toolkit slug is registered in toolkitVersions — i.e. getToolkitVersion returns 'latest' — while body.dangerouslySkipVersionCheck is falsy.

Common situations: Upgrading to an SDK version that enforces version pinning; using a toolkit whose version was never fetched/cached; toolkit slug missing on the tool object so it falls back to 'unknown' and the version lookup misses; copying older examples that omit version.

Related errors

• Invalid tool execute parameters
• Invalid tool execute session parameters
• ComposioRequestCancelledError
• Invalid tool proxy parameters
• Invalid parameters passed to set webhook subscription

AI-assisted analysis of ComposioHQ/composio@64b1b85502 (2026-08-28). Data as JSON: /api/errors/cb4a8719b858b9b5. Report an issue: GitHub.