Skip to content
CC Switch WikiUnofficial Community Wiki

502 Bad Gateway - CC Switch

Quick fix

Codex/Claude Desktop reports 502 due to CLI proxy conflicts or app-server bypassing proxy. Remove proxy config or downgrade versions to fix.

Symptom

Section titled “Symptom”
Error output
unexpected status 502 Bad Gateway: Unknown error, url: http://127.0.0.1:15721/v1/responses

Cause

Section titled “Cause”

This 502 error in cc-switch has several different trigger mechanisms depending on the tool and version used.

For Codex, there are two scenarios. First, Codex v0.137.0-alpha.4 adopts an app-server architecture where the CLI/GUI connects to an in-process app-server via WebSocket, and the app-server directly connects to the external API, completely bypassing the base_url configured in config.toml. This causes the cc-switch proxy (127.0.0.1:15721) to fail to intercept requests, and the routing panel shows 0 requests and 0 connections. Second, a regression was introduced when upgrading cc-switch from 3.17.0 to 3.20.0; the same configuration works fine in 3.17.0, but in 3.20.0 the cc-switch local proxy fails when processing upstream requests and returns 502.

For Claude Desktop's Code mode, the issue lies in the association between the Claude Code CLI's JSON configuration and Desktop's Code mode. If a user adds a VPN proxy address (e.g., 127.0.0.1:7890) to the CLI's JSON configuration, even if Desktop is configured with the cc-switch routing address (127.0.0.1:15721), Code mode will be unable to connect to cc-switch due to the proxy conflict, resulting in a 502 error. Additionally, Claude Code and Desktop introduced a regression after version 2.1.220, causing them to no longer support third-party providers such as DeepSeek.

Fix

Section titled “Fix”

  1. For Claude Desktop Code mode reporting 502: open the Claude Code CLI JSON configuration file in cc-switch and delete the proxy line (e.g., "proxy": "http://127.0.0.1:7890"). Note: after removal, the CLI will not be able to directly connect to foreign models; switch configurations as needed.

  2. For the regression issue in Claude Code/Desktop after 2.1.220: roll back Claude Code or Claude Desktop to version 2.1.220 or earlier.

  3. For the 502 regression caused by cc-switch 3.20.0 affecting Codex: uninstall cc-switch 3.20.0 and reinstall 3.17.0.

  4. For the Codex v0.137.0-alpha.4 app-server architecture bypassing the proxy: downgrade Codex to 0.80.0 (the last version supporting wire_api = "chat"), or use an external protocol conversion proxy (e.g., yangfei4913438/codex-deepseek or router-for-me/CLIProxyAPI).

Affected Versions

Section titled “Affected Versions”
ToolClaude Code / Codex
Versioncc-switch 3.16.1 - 3.20.0, Codex v0.137.0-alpha.4, Claude Code/Desktop 2.1.220+
PlatformsWindows

Source Issues

Section titled “Source Issues”

This page is distilled from 4 real issues

FAQ

Section titled “FAQ”
Why does the cc-switch routing panel show 0 requests and 0 connections, but Codex still reports 502?
Because Codex v0.137.0-alpha.4 adopts an app-server architecture, requests no longer go through the base_url configured in config.toml. Instead, the app-server directly connects to the external API, causing the cc-switch proxy to be completely bypassed.
Why does Claude Desktop's Code mode report 502, but cowork mode works fine?
Claude Desktop's Code mode is associated with the Claude Code CLI configuration. If the CLI's JSON configuration includes a VPN proxy address, Code mode cannot correctly connect to the cc-switch routing address. Removing the proxy line from the CLI configuration resolves this.
The same Codex configuration works fine in cc-switch 3.17.0, so why does it report 502 in 3.20.0?
This is a regression introduced in cc-switch 3.20.0. Uninstalling 3.20.0 and reinstalling 3.17.0 restores normal operation.
After updating Claude Code/Desktop, using DeepSeek reports 502. What should I do?
Claude Code and Desktop introduced a regression after 2.1.220, no longer supporting third-party providers such as DeepSeek. You need to roll back Claude Code or Desktop to version 2.1.220 or earlier.
Section titled “Related problems”
unexpected status 404 Not FoundUpgrade cc-switch to v3.16.4+ and set the upstream format explicitly to Chat Completions on the Codex provider form.4 issues mergedThird-party model still claims based on GPT-5 - CodexMove the `baseInstructions` override out of the `if profile != ProxyChat` block so it applies to ProxyChat. Currently it is not injected even when set.1 issues merged<!-- Failed to upload "image.png" -->Screenshot upload failures do not affect the issue itself; please describe the error message in text.10 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.