googleapis/mcp-toolbox · error

tool execution failed: %w

Error message

tool execution failed: %w

What it means

Wraps any error returned by tool.Invoke during a direct `toolbox invoke` CLI run. The tool's database/backend call itself failed (bad SQL, connection failure, permission denial, etc.) and the CLI surfaces the underlying cause via %w (cmd/internal/invoke/command.go:151-156).

Source

Thrown at cmd/internal/invoke/command.go:153

		return errMsg
	}

	// Client Auth not supported for ephemeral CLI call
	requiresAuth, err := tool.RequiresClientAuthorization(src)
	if err != nil {
		errMsg := fmt.Errorf("failed to check auth requirements: %w", err)
		opts.Logger.ErrorContext(ctx, errMsg.Error())
		return errMsg
	}
	if requiresAuth {
		errMsg := fmt.Errorf("client authorization is not supported")
		opts.Logger.ErrorContext(ctx, errMsg.Error())
		return errMsg
	}

	result, err := tool.Invoke(ctx, src, parsedParams, "")
	if err != nil {
		errMsg := fmt.Errorf("tool execution failed: %w", err)
		opts.Logger.ErrorContext(ctx, errMsg.Error())
		return errMsg
	}

	// Print Result
	output, err := json.MarshalIndent(result, "", "  ")
	if err != nil {
		errMsg := fmt.Errorf("failed to marshal result: %w", err)
		opts.Logger.ErrorContext(ctx, errMsg.Error())
		return errMsg
	}
	fmt.Fprintln(opts.IOStreams.Out, string(output))

	return nil
}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Read the wrapped cause after 'tool execution failed:' — it carries the actual backend error and fix that first.
2. Verify the tool's source (database) is reachable: check host, port, credentials, and network/VPC from the machine running the CLI.
3. Run `toolbox invoke` again with corrected parameters to rule out param-driven query errors.
4. Test the tool's statement directly against the database (psql/mysql console) to isolate SQL problems.
5. Update credentials/permissions (DB user grants, service-account roles) if the cause is access-denied.

Example fix

// before
$ toolbox tools invoke search-items '{"id": "x"}'
// error: tool execution failed: failed to connect to `host=10.0.0.5 user=admin database=app`
// after: fix the source config then retry
sources:
  my-pg-instance:
    kind: postgres
    host: 127.0.0.1
    port: 5432
    dbName: app
    user: admin

// Pre-check DB connectivity before invoking:
conn, err := sql.Open("pgx", dsn)
if err != nil { log.Fatal(err) }
if err := conn.PingContext(ctx); err != nil { log.Fatalf("source unreachable: %v", err) }

// CLI returns exit code 1; capture stderr and inspect the wrapped cause:
out, err := exec.Command("toolbox", "invoke", "my-tool", paramsJSON).CombinedOutput()
if err != nil {
    var cause string
    if i := strings.Index(string(out), "tool execution failed:"); i >= 0 {
        cause = strings.TrimSpace(string(out)[i+len("tool execution failed:"):])
    }
    fmt.Fprintf(os.Stderr, "invoke failed: %v (cause: %s)\n", err, cause)
    os.Exit(1)
}

When it happens

Trigger: `toolbox invoke <tool> '{...}'` where the tool executes but its backend operation errors: invalid SQL statement, unreachable database source, failed connection pool, insufficient DB permissions, or a parameter the backend rejects.

Common situations: Database host/port wrong in the source config so the pool cannot connect; SQL syntax error in the tool's statement; IAM/service-account lacking access to the table; API-based tools (e.g. HTTP sources) returning non-2xx responses.

Related errors

• failed to initialize resources: %w
• tool %q not found
• unable to retrieve source for tool %s
• params must be a valid JSON string: %w
• error getting parameters for tool: %w

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/913aed3954b7832a. Report an issue: GitHub.