Skip to content
CC Switch WikiUnofficial Community Wiki

cc-switch Local Proxy FAQ: 502 Bad Gateway, Timeouts, Unable to Delete Configurations, Missing UI, and Inconsistent Failover Status

Quick fix

Proxy issues often stem from unsupported official providers, unapplied settings, or unsynchronized UI state;

Symptom

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

Cause

Section titled “Cause”

This cluster covers several proxy-related issues. Main causes include: 1) To reduce account-ban risk, the local proxy does not support official providers, so requests to official models may time out or fail when the proxy is enabled; 2) deleting the only remaining provider is restricted by design, so add another provider first; 3) when the proxy is enabled, it takes over the local configuration file, so inspecting that file may not show the actual request destination; 4) in some versions, the failover toggle is decoupled from local proxy takeover, leaving the UI interactive while backend behavior differs; 5) in WSL, the proxy may need to be turned off and back on to take effect. Different error variants—timeouts, 502 errors, missing UI, and inability to delete—have different causes and do not share one fix.

Fix

Section titled “Fix”

  1. If you use an official provider with OAuth login, turn off the local proxy or switch to a third-party provider; the local proxy does not support official providers.

  2. If you cannot delete the only remaining provider, add an official or third-party provider first, then delete the original provider.

  3. When switching providers with the proxy enabled, do not use the local configuration file to determine whether the switch succeeded. Check actual requests, the usage panel, or provider dashboard data. If the change has not taken effect, turn the proxy off and back on.

  4. If the proxy does not work in WSL, try turning it off and back on. If it still does not work, confirm that the proxy works on Windows, and note the known issue with WSL addresses other than 127.0.0.1.

  5. If the local proxy or failover toggle disappears from the home page, open the local proxy settings and enable the option to show the local proxy toggle on the home page. For failover display issues, upgrade to v3.12.3 or later to verify the fix.

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 27 real issues

FAQ

Section titled “FAQ”
Why do official models time out or return 502 when the proxy is enabled?
To reduce account-ban risk, the local proxy does not support official providers. Calls using official login methods are unrelated to proxy takeover by cc-switch. Turn off the proxy or switch to a third-party provider.
How do I delete all Codex proxy configurations?
You cannot delete the only remaining provider. Add another provider, then delete the current one. If you do not want to use it, add an empty official provider as a placeholder.
Why did the configuration file not change after I switched providers with the proxy enabled?
When the proxy is enabled, it takes over the local configuration file. The request address and provider shown in the file may not be meaningful; use actual request data or the usage panel instead.
What should I do if the local proxy UI disappears from the home page?
Starting with v3.11.0, you may need to enable “Show local proxy toggle on home page” manually in the local proxy settings. The failover toggle display issue was fixed after v3.12.0; upgrade to v3.12.3 or later to verify.
What should I do if the proxy does not work in WSL?
Some users resolved this by turning the proxy off and back on. There is a known issue with configuring a non-127 address in WSL. If the proxy runs on the Windows host, account for WSL network address limitations.
Why can the failover toggle appear or be usable when the proxy is not enabled?
In some versions, the home page failover toggle is decoupled from local proxy takeover, which can cause inconsistent state. Most documentation and backend logic still assume that the proxy is running and the application has taken it over. Upgrade and confirm that the fix is present in your version.
Section titled “Related problems”
Cannot start normally: window unresponsive, system requires force quitUpdate CC Switch to 4.0 or the latest version and retry. If it persists, provide the full version, steps, logs, and screenshots.1 issues merged<thinking> tags output as body text in Claude CodeChanging the provider's apiFormat from openai_chat to anthropic, if supported upstream, can bypass inline <thinking> leakage.1 issues mergedSelect Model Menu Still Shows Pre-Switch Model List - CodexClose existing Codex sessions, run `codex app-server daemon restart`, and upgrade CC Switch to v4.0.7 or later for detection and restart prompts.3 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.