ComposioHQ/composio · error · ValidationError

Invalid tool execute parameters

Error message

Invalid tool execute parameters

What it means

ValidationError('Invalid tool execute parameters') is thrown by parseToolExecuteParams when the body fails ToolExecuteParamsSchema.safeParse. This is a client-side Zod guard that fires before any network call; the underlying ZodError is attached as cause and lists exactly which fields failed.

Source

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

    result = await this.applyAfterExecuteModifiers(
      tool,
      {
        toolSlug: slug,
        toolkitSlug,
        result,
      },
      (modifiers as ExecuteToolModifiers).afterExecute,
      requestOptions
    );

    return result;
  }

  private parseToolExecuteParams(body: ToolExecuteParams): ToolExecuteParams {
    const executeParams = ToolExecuteParamsSchema.safeParse(body);
    if (!executeParams.success) {
      throw new ValidationError('Invalid tool execute parameters', { cause: executeParams.error });
    }
    return executeParams.data;
  }

  /**
   * Executes a given tool with the provided parameters.
   *
   * This method calls the Composio API to execute the tool and returns the response.
   *
   * **Version Control:**
   * By default, manual tool execution requires a specific toolkit version. If the version resolves to "latest",
   * the execution will throw a `ComposioToolVersionRequiredError` unless `dangerouslySkipVersionCheck` is set to `true`.
   * This helps prevent unexpected behavior when new toolkit versions are released.
   *
   * @param {string} slug - The slug/ID of the tool to be executed
   * @param {ToolExecuteParams} body - The parameters to be passed to the tool
   * @param {string} [body.version] - The specific version of the tool to execute (e.g., "20250909_00")
   * @param {boolean} [body.dangerouslySkipVersionCheck] - Skip version validation for "latest" version (use with caution)

View on GitHub (pinned to 64b1b85502)

Solutions

1. Inspect error.cause (ZodError .issues) to see exactly which paths failed and fix those fields
2. Ensure arguments is a plain object — JSON.parse strings first — and required fields like toolId are present with correct types
3. Pre-validate with the exported ToolExecuteParamsSchema in dev/tests to catch shape mismatches before calling execute

Example fix

// before
await tools.execute({ toolId, arguments: '{"query": "hi"}' }); // string

// after
await tools.execute({ toolId, arguments: { query: 'hi' } });

import { ToolExecuteParamsSchema } from '@composio/core';
const parsed = ToolExecuteParamsSchema.safeParse(params);
if (!parsed.success) {
  throw new Error(parsed.error.issues.map(i => `${i.path}: ${i.message}`).join('; '));
}

const isRecord = (v: unknown): v is Record<string, unknown> =>
  typeof v === 'object' && v !== null && !Array.isArray(v);

try {
  await tools.execute(params);
} catch (e) {
  if (e instanceof ValidationError) console.error(e.cause?.issues ?? e.cause);
}

When it happens

Trigger: Calling the tool-execution path that routes through parseToolExecuteParams (executeToolFn / executeParams) with a body that violates ToolExecuteParamsSchema — wrong types (arguments not an object, connectedAccountId not a string), missing required fields, or unexpected field shapes.

Common situations: Passing a raw LLM-generated JSON string as arguments instead of a parsed object; omitting required fields; snake_case keys copied from API docs (tool_id vs toolId); schema drift after an SDK upgrade tightening constraints.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Invalid tool execute session parameters
• Invalid tool proxy parameters
• Invalid parameters passed to set webhook subscription
• Invalid parameters passed to list triggers
• Invalid parameters passed to create trigger

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