google-gemini / google-gemini/gemini-cli

Feature: Add structured error classification and recovery hints to tool error responses

Open
#23,156 4 comments 0 reactions 0 assignees View on GitHub
area/core effort/medium kind/enhancement priority/p2 Stale status/bot-triaged
Dominant language
TypeScript
Stars
107k
Forks
14.6k
Avg merge
2d 3h
Merged PRs (30d)
45

Description

### What would you like to be added?

Tool error responses sent to the model are currently unstructured strings (e.g., `{ "error": "File not found: /src/utils/halper.ts" }`), forcing the model to infer error category and recovery strategy from natural language. This leads to suboptimal recovery behavior — the model may retry fatally broken operations or give up on recoverable errors.

Add structured metadata fields to tool error `functionResponse.response`:
- `error_type` — the `ToolErrorType` enum value (e.g., `file_not_found`, `permission_denied`)
- `recoverable` — boolean indicating whether the error is recoverable
- `hint` — actionable recovery guidance specific to the error type

### Why is this needed?

The existing `ToolErrorType` enum and `isFatalToolError()` function already classify errors internally, but this classification is not surfaced to the model. By including structured metadata in error responses, the model can:

1. Distinguish recoverable errors (file not found → try glob) from fatal ones (no space left → stop writing)
2. Follow specific recovery guidance rather than guessing
3. Avoid retry loops on fatal errors

This is backward compatible — new fields only appear when `errorType` is defined.

### Additional context

All three `createErrorResponse` sites (ToolExecutor, CoreToolScheduler, Scheduler) should be updated for consistency.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.