[Bug] API Error 400 with Gemini model: Invalid JSON payload received. Unknown name "$schema"

[kfxmvp]

What happened?

When using the Gemini model (specifically gemini-2.5-pro as shown in the terminal), I encountered a crash with an API Error 400. The error message specifically states Invalid JSON payload received. Unknown name "$schema", indicating that the $schema field in the tool parameters is being rejected by the API.

It appears that when MCP tools (which use parametersJsonSchema) are processed, the schema is passed directly to the API without sanitization. The Gemini API does not support the $schema property in the function declaration parameters.

Terminal Output:
✕ [API Error: 400 400: Invalid JSON payload received. Unknown name "$schema" at 'tools[0].function_declarations[0].parameters': Cannot find field. Invalid JSON payload received. Unknown name "$schema" at 'tools[0].function_declarations[10].parameters': Cannot find field. Invalid JSON payload received. Unknown name "$schema" at 'tools[0].function_declarations[11].parameters': Cannot find field.]

Relevant Code Location:
In packages/core/src/core/openaiContentGenerator/converter.ts

What did you expect to happen?

The application should automatically sanitize tool parameters before sending them to the Gemini API. Specifically, it should remove the $schema property from the JSON schema, as it is not a valid field for the tool definition in the Gemini API's expected format. This would prevent the 400 error and allow tool usage to proceed normally.

Client information

Client Information

Run qwen to enter the interactive CLI, then run the /about command.

$ qwen /about
╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│                                                                                                                                       │
│ 关于 Qwen Code                                                                                                                        │
│                                                                                                                                       │
│ CLI 版本                                       0.4.1                                                                                  │
│ Git 提交                                       628094ec                                                                               │
│ 模型                                           gemini-2.5-pro                                                                         │
│ 沙箱                                           no sandbox                                                                             │
│ 操作系统平台                                   darwin                                                                                 │
│ 操作系统架构                                   arm64                                                                                  │
│ 操作系统版本                                   25.1.0                                                                                 │
│ Node.js 版本                                   v20.19.3                                                                               │
│ NPM 版本                                       10.8.2                                                                                 │
│ 会话 ID                                        fd9d960f-dc16-4d71-8da5-b4954884efbf                                                   │
│ 认证方式                                       openai                                                                                 │
│ 基础 URL                                      https                                                                                    │
│ 内存使用                                       227.9 MB                                                                               │
│                                                                                                                                       │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Login information

No response

Anything else we need to know?

No response

[afarber]

Hi @kfxmvp looking at packages/core/src/core/openaiContentGenerator/converter.ts, when MCP tools have parametersJsonSchema, it creates a shallow copy but doesn't strip out $schema

The docs at docs/tools/mcp-server.md mention that $schema properties should be removed for API compatibility, but it looks like that's only documented, not implemented for this code path.

Maybe you could add something like delete paramsCopy['$schema'] right after line 200...

[kfxmvp]

Hi @afarber , thanks a lot for your feedback!

I completely agree with your assessment. This is indeed the root cause of the Gemini API errors. In fact, beyond just $schema, other modern JSON Schema features—such as multi-type definitions (e.g., ["string", "null"]) and numeric exclusiveMinimum—also cause compatibility issues under the strict OpenAPI 3.0 requirements of the Gemini API.

I've just submitted a PR that systematically addresses this by introducing a configurable schema compliance mechanism. This fix strictly follows the OpenAPI 3.0.3 Specification and Google Vertex AI Function Calling Documentation, implementing semantic downgrading for tool definitions sent to Gemini (e.g., stripping $schema, handling nullable types, etc.).

Let me know what you think!

[afarber]

Reviewed the PR #1214 and left a comment with a suggested doc update.