ComposioHQ/composio · error · TypeError

Direct execution options and modifiers cannot be used with a

Error message

Direct execution options and modifiers cannot be used with a Tool Router session

What it means

Composio's BaseProvider.assertToolCallExecutionOptions throws a TypeError when a caller supplies ExecuteToolFnOptions or ExecuteToolModifiers while targeting a Tool Router session instead of a string tool call ID. Options and modifiers only apply to direct execution of a single tool call. Mixing the two is an API misuse, so the SDK fails fast rather than silently ignoring the parameters.

Source

Thrown at ts/packages/core/src/provider/BaseProvider.ts:75

    body: ToolExecuteParams,
    modifers?: ExecuteToolModifiers
  ): Promise<ToolExecuteResponse> {
    if (!this._globalExecuteToolFn) {
      throw new ComposioGlobalExecuteToolFnNotSetError('executeToolFn is not set');
    }

    // For provider controlled execution, always skip version check.
    return this._globalExecuteToolFn(toolSlug, body, modifers);
  }

  /** Reject direct-only configuration when execution is bound to a session. */
  protected assertToolCallExecutionOptions(
    target: ToolCallExecutionTarget,
    options?: ExecuteToolFnOptions,
    modifiers?: ExecuteToolModifiers
  ): void {
    if (typeof target !== 'string' && (options !== undefined || modifiers !== undefined)) {
      throw new TypeError(
        'Direct execution options and modifiers cannot be used with a Tool Router session'
      );
    }
  }

  /**
   * Execute normalized provider arguments against either the direct tools API or
   * the Tool Router session that produced the model-visible tools.
   */
  protected async executeToolForTarget(
    target: ToolCallExecutionTarget,
    toolSlug: string,
    arguments_: Record<string, unknown>,
    options?: ExecuteToolFnOptions,
    modifiers?: ExecuteToolModifiers
  ): Promise<ToolExecuteResponse> {
    this.assertToolCallExecutionOptions(target, options, modifiers);

View on GitHub (pinned to 64b1b85502)

Solutions

Remove the options/modifiers arguments when passing a Tool Router session as the target
If you need options/modifiers, pass a string tool call ID as the target and execute the tool call directly
Check the SDK types for ExecuteToolCallExecutionTarget to confirm which target type you are using

Example fix

// before
await provider.executeToolForTarget(routerSession, toolCall, { timeout: 5000 }, modifiers);

// after
await provider.executeToolForTarget(routerSession, toolCall);

Defensive patterns

Strategy: validation

Validate before calling

const isDirectTarget = (t: unknown): t is string => typeof t === 'string';
if (!isDirectTarget(target) && (options || modifiers)) {
  throw new TypeError('Drop options/modifiers when using a Tool Router session');
}

Type guard

function isToolRouterTarget(t: unknown): t is ToolRouterSession {
  return typeof t !== 'string' && t !== null && typeof t === 'object';
}

Try / catch

catch (e) { if (e instanceof TypeError && e.message.includes('Tool Router session')) { /* drop options/modifiers and retry */ } throw e; }

Prevention

Branch your code paths: router sessions vs direct tool-call IDs
Let types guide you: never pass extra args when target is not a string

When it happens

Trigger: Calling executeToolForTarget or handleToolCalls with a non-string target (e.g. a ToolRouter/session object) while also passing `options` (timeout, abort signal, etc.) or `modifiers` (custom modifiers array) in the same call.

Common situations: Migrating code that executed a single tool call by ID to the Tool Router API and forgetting to strip per-call options/modifiers; copy-pasting provider-level execute calls into router-based flows; upgrading to an SDK version where this guard was added.

Related errors

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