Skip to content
CC Switch WikiUnofficial Community Wiki

cc-switch local proxy problems: 502 Bad Gateway, timeouts, cannot delete a provider, missing UI, inconsistent failover state

Quick fix

Usually caused by unsupported official providers, config not applying, or UI state drift. Check proxy mode, provider type, and takeover state.

Symptom

Section titled “Symptom”
Error output
unexpected status 502 Bad Gateway:

Cause

Section titled “Cause”

This cluster groups several proxy-related problems. The main mechanisms are: 1) the local proxy does not support official providers, as a ban-risk precaution, so reaching official models with the proxy on times out or errors; 2) the last remaining provider cannot be deleted — that is a design limit, add another provider first, then delete; 3) once the proxy is on it takes over the local config file, so reading that file does not tell you where requests actually go; 4) in some versions the failover toggle is decoupled from local-proxy takeover state, so the UI accepts input while the backend semantics disagree; 5) under WSL the proxy may need to be turned off and on again before it takes effect. The error variants — timeout, 502, missing UI, cannot delete — have different root causes and there is no single fix.

Fix

Section titled “Fix”

  1. If you are on an official provider (OAuth sign-in), turn the local proxy off or switch to a third-party provider. The local proxy does not support official providers.

  2. If the last remaining provider cannot be deleted, add an official or third-party provider first, then delete the original one.

  3. When switching provider with the proxy on, do not judge success by the contents of the local config file. Go by the actual requests, the usage panel, or the provider dashboard. If it did not take effect, turn the proxy off and on again.

  4. If the proxy does nothing under WSL, try turning it off and on again. If it still does nothing, confirm the proxy works on the Windows side and note the known problem with non-127.0.0.1 addresses under WSL.

  5. If the local-proxy or failover toggle disappeared from the main page, open local proxy settings and turn on 在主页面显示本地代理开关 (show the local proxy toggle on the main page). For failover display problems, upgrade to v3.12.3 or newer and check again.

Affected Versions

Section titled “Affected Versions”
ToolUnknown
Version3.8.3 - 3.11.0
PlatformsWindowsmacOSLinux

Source Issues

Section titled “Source Issues”

This page is distilled from 26 real issues

FAQ

Section titled “FAQ”
Why do official models time out or return 502 with the proxy on?
The local proxy does not support official providers, as a ban-risk precaution. Calls made through an official sign-in have no direct relationship with cc-switch proxy takeover. Turn the proxy off, or switch to a third-party provider.
How do I delete all the Codex proxy configuration?
The last remaining provider cannot be deleted. Create another provider first, then delete the current one. If you do not want to use it, add an empty official provider as a placeholder.
I switched provider with the proxy on and the config file didn't change. Why?
With the proxy on, it takes over the local config file, so the request address and provider recorded there may be meaningless. Go by the actual request data or the usage panel.
The local proxy UI disappeared from the main page. What now?
From v3.11.0 on, the local proxy UI may have to be enabled manually with 在主页面显示本地代理开关 (show the local proxy toggle on the main page) in local proxy settings. The failover toggle display problem was fixed after v3.12.0; upgrade to v3.12.3 or newer and check again.
The proxy does nothing under WSL. What now?
Some users fixed it by turning the proxy off and on again. Configuring a non-127 address under WSL still has known problems; if the proxy runs on the Windows host, mind the WSL network address limits.
Why is the failover toggle shown and operable even when the proxy is off?
In some versions the failover toggle on the home page is decoupled from local-proxy takeover state, which can leave the two inconsistent. The docs and most backend logic still assume the proxy is started and the app has been taken over. Upgrade and confirm your version has the fix.
Section titled “Related problems”
Missing API key · Run /login - Claude CodeClear the conflicting ANTHROPIC_BASE_URL environment variable, or upgrade CC Switch to use its built-in environment variable conflict detection.2 issues mergedUnsupported parameter: 'max_tokens'The route forwards max_tokens to a model that only accepts max_completion_tokens. Verify parameter support or wait for a cc-switch fix.1 issues mergedbash: cannot set terminal process group - cc-switchA known 3.18.0 bug when checking the local proxy environment on Linux. Downgrade below 3.18.0 and configure the proxy in the terminal by hand.5 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.