Skip to content
CC Switch WikiUnofficial Community Wiki

Codex Kimi HTTP 400 moonshot flavored json schema - CC Switch

Quick fix

Upgrade CC Switch to the latest version; the proxy automatically cleans Kimi-incompatible $ref sibling keywords and tool schemas missing root-level type.

Symptom

Section titled “Symptom”
Error output
CC Switch local proxy failed while handling Codex endpoint /responses. Provider: Kimi For Coding; model: k3; upstream_status: HTTP 400; cause: tools.function.parameters is not a valid moonshot flavored json schema, details: <At path '$defs.__schema20': when using $ref, type should be defined in the referenced schema instead of the parent schema>

Cause

Section titled “Cause”

The parameter schemas of Codex built-in tools (such as automation_update) are auto-generated by Zod or Rust schemars, following the JSON Schema 2020-12 spec, which allows `$ref` to appear alongside sibling keywords like `type` and `description`, and also allows root-level `oneOf` without a `type` field. However, the Moonshot (Kimi) server uses legacy validation (draft-07 semantics), where `$ref` nodes do not allow any sibling keywords, and it strictly requires `tools[].function.parameters.type` to equal `"object"`. CC Switch originally forwarded `tools` as-is during the Responses → Chat Completions conversion, causing Kimi to return 400 for every request with tools.

Some users also encounter a second variant: fields in `required` are not defined in `properties` (dangling references), which also triggers 400. Additionally, in early versions (3.16.3), presets for providers like Volcano AgentPlan hardcoded `apiFormat` to be overridden as `openai_chat`, which coupled with the "local routing mapping" switch, caused inability to use the native Responses API and also resulted in HTTP 400.

Fix

Section titled “Fix”

  1. Upgrade CC Switch to the latest version. v3.16.4 decoupled the upstream format selector from the local routing mapping switch; v3.18.0 fixed the root-level missing `type` issue (#4706 / #5315); the latest main branch (#6863, commit db41d7018) automatically moves `$ref` with sibling keywords into `allOf` and handles dangling `required` references when it detects the upstream is Moonshot/Kimi.

  2. If the error persists after upgrading, try deleting the Kimi provider configuration, re-applying for an API key, and re-adding it.

  3. If using providers like Volcano AgentPlan that support the native Responses API, ensure the "local routing mapping" switch is not enabled (or directly select the Responses protocol in the new version) to avoid being forced to override as openai_chat.

  4. If a specific session keeps failing (session stuck), create a new session as a temporary workaround—because the tool_search_output containing incompatible schemas permanently remains in the old session history.

Affected Versions

Section titled “Affected Versions”
ToolCodex
Version3.16.3 - 3.20.1（受影响版本；3.16.4 起逐步修复，最新版已完全修复）
PlatformsmacOSWindows

Source Issues

Section titled “Source Issues”

This page is distilled from 8 real issues

FAQ

Section titled “FAQ”
What should I do if the same 400 error still occurs after upgrading to the latest version?
The maintainers have fixed this on the main branch via #6863 and verified end-to-end (HTTP 400 → 200); the fix will be released in the next version. If the current latest release does not yet include this commit, you can refer to the approach in #6867 to merge and compile the branch yourself, or wait for the next official release.
Not just the k3 model, but kimi-k2.7-code and kimi-k2.7-high-speed also report 400. Is this the same issue?
Yes, all Kimi/Moonshot models use the same strict JSON Schema validation, regardless of the specific model.
Why does a new session work fine, but a specific session fails on every request?
After Codex Desktop dynamically loads tools via tool_search, the tool_search_output (containing full tool definitions) permanently remains as a history item in the input of subsequent requests. If that tool schema is incompatible with Kimi validation rules, every subsequent round in that session will return 400. Creating a new session bypasses this.
Is there a temporary workaround without waiting for the new version release?
Some users wrote a ~100-line local cleaning proxy in Python attached upstream of CC Switch, which recursively traverses tool schemas, merges `$ref` sibling keywords into `$defs` clones, promotes anyOf/oneOf object branches to the root, and prunes dangling references in `required`. See the solution description in issue #6867.
Will Codex CLI also encounter this issue?
Codex CLI's own 17 built-in tool schemas have no `$defs` and do not trigger this issue. This problem is only caused by dynamic tools like automation_update injected by Codex App (desktop).
Section titled “Related problems”
kimi k2 reports 404 - CC SwitchA 404 from the connection test does not mean Kimi is unavailable. Set ANTHROPIC_BASE_URL to https://api.kimi.com/coding/ and verify by running Claude Code.4 issues mergedimage_detail is invalid: Codex StepFun Screenshot Request FailureUpgrade CC Switch to v3.20.4; it changes tool screenshot detail: "original" to the StepFun-accepted "auto".1 issues mergedAuth conflictLog out of the official Claude login, clear conflicting ANTHROPIC_* variables, set hasCompletedOnboarding to true in ~/.claude.json, and restart the terminal.6 issues merged

This is an unofficial community wiki with no affiliation to the cc-switch authors or the project itself. Its content is compiled from the project's public GitHub issues. This site distributes no software.