alibaba/page-agent · error · InvokeError

TOOL_EXECUTION_ERROR

TOOL_EXECUTION_ERROR

Error message

Tool execution failed: ${(error as Error)?.message}

What it means

The tool's own execute() function threw while running; invoke() rethrows it as InvokeError TOOL_EXECUTION_ERROR with the original error attached, unless it is an AbortError (cancellation), which is rethrown as-is. This is the tool's runtime failure, not an LLM protocol issue.

Source

Thrown at packages/llms/src/OpenAIClient.ts:243

		const validation = tool.inputSchema.safeParse(parsedArgs)
		if (!validation.success) {
			console.error(z.prettifyError(validation.error))
			throw new InvokeError(
				InvokeErrorTypes.INVALID_TOOL_ARGS,
				'Tool arguments validation failed',
				validation.error,
				data
			)
		}
		const toolInput = validation.data

		// 5. Execute tool
		let toolResult: unknown
		try {
			toolResult = await tool.execute(toolInput)
		} catch (error: unknown) {
			if ((error as any)?.name === 'AbortError') throw error
			throw new InvokeError(
				InvokeErrorTypes.TOOL_EXECUTION_ERROR,
				`Tool execution failed: ${(error as Error)?.message}`,
				error,
				data
			)
		}

		// Return result
		return {
			toolCall: {
				name: toolCallName,
				args: toolInput,
			},
			toolResult,
			usage: {
				promptTokens: data.usage?.prompt_tokens ?? 0,
				completionTokens: data.usage?.completion_tokens ?? 0,
				totalTokens: data.usage?.total_tokens ?? 0,

View on GitHub (pinned to d02db1ee7c)

Solutions

1. Read the wrapped message and error.cause stack to find which tool failed and why
2. Fix the tool's internal error (null checks, stale index handling, retries inside the tool)
3. In agent loops, catch TOOL_EXECUTION_ERROR and feed the message back to the LLM so it can correct course
4. AbortError is intentionally rethrown — don't swallow it when implementing cancellation

Example fix

// before
const result = await agent.next() // tool throws, whole run crashes

// after
try {
  const result = await agent.next()
} catch (e) {
  if (e.code === 'TOOL_EXECUTION_ERROR') {
    messages.push({ role: 'tool', content: `Error: ${e.message}` }) // let LLM retry
  } else throw e
}

null

function isToolExecutionError(e: unknown): e is InvokeError {
  return e instanceof InvokeError && e.code === InvokeErrorTypes.TOOL_EXECUTION_ERROR
}

try {
  await agent.next()
} catch (e) {
  if (isToolExecutionError(e)) {
    conversation.push({ role: 'tool', content: `Error: ${e.message}` }) // let the model recover
    return await agent.next()
  }
  throw e
}

When it happens

Trigger: await tool.execute(toolInput) rejects: e.g. a DOM action tool failing because the element index no longer exists, a network tool timing out, or any bug inside the tool implementation.

Common situations: PageController element index stale after page changed between updateTree and click; tool code accessing undefined properties; external services down; passing invalid (schema-valid but semantically wrong) values to the tool.

Related errors

• NO_TOOL_CALL
• INVALID_TOOL_ARGS
• [PageAgent] LLM configuration required. Please provide: base
• [PageAgent] LLMConfig.temperature is deprecated and will be

AI-assisted analysis of alibaba/page-agent@d02db1ee7c (2026-08-28). Data as JSON: /api/errors/e06664c9a0b3104e. Report an issue: GitHub.