Improve Gemini API error handling and user feedback

[ystknsh]

概要

Gemini APIでpluginが増えた際のtools複雑エラーに対応し、エラーハンドリングとユーザーへのフィードバックを改善する

背景

• プラグイン数が増えるとGemini APIでtools複雑エラーが発生する
• role設定を絞ることで回避可能
• 設定画面でwarnをだすのがよい? geminiでもmodel依存？ 要検討
• 現状、400/500エラーがコンソールにのみ出力され、ユーザーに伝わっていない

---

🤖 Auto-generated by Claude Code

[masap]

@ystknsh Could you share the actual test case or test code to reproduce it?

[ystknsh]

Thanks for your interest!

We tested with 2 people on our team and got mixed results:

• Person A: Can reproduce
• Person B: Cannot reproduce

We're looking into what's causing the difference. Will share updates here.

setting

prompt + error message

error message (OCR)

• SES Removing unpermitted intrinsics lockdown-install.js:1 A • WARNING: Multiple instances of Three. js being imported. three-vrm.module-DJ7DURJm.js:11261 SENDING USER MESSAGE "悟空の絵" useTextSession.ts: 131 • POST http://localhost:5173/api/text/generate 500 (Internal Server useTextSession.ts: 147 Error) • Generate API error: 500 {"success": false, "error": "Failed to generate useTextSession.ts:162 text" , "details": "{"error": {"code": 400, \ "message": "The specified schema produces a constraint that has too many states for serving. Typical causes of this error are schemas with lots of text (for example, very long property or enum names), schemas with long array length limits (especially when nested), or schemas using complex value matchers (for example, integers or numbers with minimum/maximum bounds or strings with complex formats like date- time)", "status": \ "INVALID_ARGUMENT\ "}} "} x • Text session request failed Error: API error: Internal Server Error - useTextSession.ts: 234 {"success": false, "error": "Failed to generate text", "details": "{"error": {"code": 400, "message": "The specified schema produces a constraint that has too many states for serving. Typical causes of this error are schemas with lots of text (for example, very long property or enum names), schemas with long array length limits (especially when nested), or schemas using complex value matchers (for example, integers or numbers with minimum/maximum bounds or strings with complex formats like date-time" ‚"status": "INVALID_ARGUMENT"}} "} at Object.sendUserMessage (useTextSession.ts: 163:15) at async Proxy. sendTextMessage (HomeView.vue: 640:16) • Session error Error: API error: Internal Server Error - HomeView. vue: 569 {"success": false, "error": "Failed to generate text" , "details": "{"error": {"code": 400, "message": "The specified schema produces a constraint that has too many states for serving. Typical causes of this error are schemas with lots of text (for example, very long property or enum names), schemas with long array length limits (especially when nested), or schemas using complex value matchers (for example, integers or numbers with minimum/maximum bounds or strings with complex formats like date-time)" ,"status": "INVALID_ARGUMENT"}} "} at Object.sendUserMessage (useTextSession.ts: 163:15) at async Proxy.sendTextMessage (HomeView.vue:640:16) →

[masap]

@ystknsh Thank you for sharing it. But in my environment, it works fine. Could you expand this field and share it? Could you disable all add-ons in your web browser and try again?

[ystknsh]

Root Cause Analysis

The error occurs when the total JSON schema complexity of all tool definitions exceeds Gemini API's internal state limit.

Key finding: tool count determines success/failure

Role type	Tools sent	Schema size	Result
Fixed role (e.g., tutor)	~15	~14,600 bytes	✅ Success
Customizable role (e.g., general)	~31	~49,300 bytes	❌ INVALID_ARGUMENT

The complex schemas of plugins like playGo (9×9 2D array), playOthello (8×8 2D array), and presentSpreadsheet (3-level nesting) contribute significantly to the total state count.

Reproduction steps

1. Configure all 5 API keys in .env (the last 3 can be dummy values since isEnabled only checks for key existence):

   OPENAI_API_KEY=<your key>
   GEMINI_API_KEY=<your key>
   EXA_API_KEY=dummy
   GOOGLE_MAP_API_KEY=dummy
   ANTHROPIC_API_KEY=dummy
   

2. Restart the dev server
3. Select a customizable role (e.g., general) with all plugins enabled
4. Set mode to Text with Google provider (e.g., gemini-2.5-flash)
5. Send any message (e.g., "悟空の絵")
6. → 500 error: "The specified schema produces a constraint that has too many states for serving"

Why reproduction results varied between people

• Role selection (stored in localStorage per browser): fixed roles send fewer tools
• API keys in .env: plugins like exa, google-map, summarize-pdf, edit-html, generate-html are only enabled when their corresponding API keys are configured
• Both factors affect the number of tool definitions included in the request

[ystknsh]

追加調査結果（Gemini API スキーマ制限の詳細）

Gemini API には 2 種類のスキーマ制限がある

閾値テストにより、Gemini API が返すエラーが 2 種類 あることが判明しました。

エラー 1: "too many states"（状態数超過）

The specified schema produces a constraint that has too many states for serving.
Typical causes: schemas with long array length limits (especially when nested),
or complex value matchers (integers/numbers with minimum/maximum bounds)

• 主な原因: playGo（9×9 2D 配列 + min/max）、playOthello（8×8 2D 配列）、presentSpreadsheet（3 階層ネスト配列）
• 全 31 ツール有効時に発生

エラー 2: "too much branching"（分岐数超過）

The specified schema produces a constraint that has too much branching for serving.
Typical causes: objects with lots of optional properties, enums with too many values,
or any_of a large number of alternative types.

• 主な原因: presentForm（optional プロパティ 15 個以上）、switchRole（enum 14 値）、mapControl（optional プロパティ多数）
• Go・Othello・Spreadsheet を無効にした 28 ツールでも発生

閾値テスト結果

ツール数	無効にしたプラグイン	結果
31	なし	❌ "too many states"
28	playGo, playOthello, presentSpreadsheet	❌ "too much branching"
27	上記 + mapControl	✅ 成功
27	上記 + scrollToAnchor（mapControl は有効）	❌ "too much branching"

同じ 27 ツールでも mapControl の有無で結果が変わるため、純粋なツール数の問題ではなく、特定プラグインのスキーマ複雑性が主因。

プロバイダー間比較（同じ 31 ツールで検証）

プロバイダー	モデル	結果
Google	gemini-2.5-flash	❌ "too many states"
Google	gemini-3-pro-preview	❌ "Request contains an invalid argument."（詳細なし）
OpenAI	gpt-5.2	✅ 成功
Anthropic	claude-sonnet-4-5	✅ 成功

→ この問題は Google Gemini API 固有。OpenAI・Anthropic は同じスキーマを問題なく処理できます。

なぜ Gemini だけが制限に引っかかるのか

Gemini API は Function Calling の JSON Schema を内部で constrained decoding に使用しています。具体的には、JSON Schema を 有限状態オートマトン（finite state automaton） に変換し、トークン生成時にそのオートマトンに沿った出力のみを許可することで、スキーマに準拠した JSON を確実に生成する仕組みです。

この方式では、スキーマの複雑さに応じてオートマトンの状態数が 指数的に増加 します：

• ネスト配列 + min/max: 各セルの状態 × 配列長の組み合わせで状態数が爆発（→ "too many states"）
• optional プロパティの組み合わせ: 各プロパティの有無で分岐し、N 個の optional プロパティで最大 2^N の分岐（→ "too much branching"）
• 大きな enum: 各 enum 値がオートマトンの分岐になる

一方、OpenAI と Anthropic はこの方式を採用していないか、より効率的な実装をしていると推測されます：

• OpenAI: ハードリミット 128 ツール。strict mode でもスキーマの状態数制限なし
• Anthropic: ツール数のハードリミットなし。数百〜数千のツールを想定した設計

公式ドキュメント・既知の issue

• Function calling | Gemini API: 推奨アクティブツール数は 10〜20 個。ハードリミットは 512 function declarations だが、スキーマ複雑性の制限はそれより遥かに厳しい
• googleapis/python-genai#660: 約 200,000 文字のスキーマで同エラー。Google 担当者は「正確なガイダンスはない」と回答。具体的な制限値は非公開
• cline/cline#7897: MCP ツールを多数有効にすると同じエラー。ワークアラウンドとして native tool calling を無効化し XML ベースに切り替え

対策方針

1. Phase 1: エラーのユーザー表示 — 現在コンソールのみに出力されている API エラーを、チャットエリアに表示する
2. Phase 2: Gemini 固有の対策 — Google プロバイダー選択時にツール数/スキーマ複雑性に応じた警告を出す。または、ツール定義のスキーマを簡略化する（optional プロパティの削減、配列サイズ制限の緩和など）

[masap]

Thank you for the detailed analysis. I was able to reproduce the issue as well. I've submitted a PR (#135) where Gemini itself selects the necessary plugins before passing them all to Gemini. While this eliminates the need for users to manually select plugins to pass to Gemini, it does increase the number of queries to Gemini, which will slow down responses. Any feedback is welcome.