Skip to content
CC Switch WikiUnofficial Community Wiki

cc-switch crashes on launch / white screen / black screen / background crash

Quick fix

Upgrade to the latest. Windows white screen: install WebView2. Proxy crash: change port, upgrade to v3.9.1+. Old macOS/Linux: use the CLI or distro package.

Symptom

Section titled “Symptom”
Error output
3.9版本开启代理后，只要claude cli发起请求，ccs先是界面卡死然后就闪退了，关闭代理后就正常了。
English translation

On version 3.9, with the proxy on, as soon as the claude cli makes a request, ccs freezes and then crashes. With the proxy off it behaves normally.

Cause

Section titled “Cause”

This cluster holds launch-time and runtime crashes with several different mechanisms. First: a panic while handling a request with the local proxy on, typically because the proxy layer truncates a log or request body across a multi-byte character boundary — for example byte index 2000 is not a char boundary. This was fixed by Proxy Panic Prevention / graceful degradation in v3.9.1. Second: a white screen or crash on Windows, usually tied to a missing WebView2, an old OS version, signature blocking, or UI/title-bar problems in later versions; v3.2.0 and v3.9.0+ each fixed part of the white/black screen family. Third: a tao event-loop assertion or state error while running in the background on Windows, such as flush_paint_messages or cannot move state from Destroyed — the issues name no definitive fix version. Fourth: a white screen, freeze, or failure to start on macOS/Linux, mostly because Tauri 2 is demanding about the OS, WebKit/GTK, hardware acceleration, and package type; older macOS and some Linux environments are better served by cc-switch-cli or a distro-specific package. There are also port conflicts that break or crash the proxy toggle, such as 7890 clashing with Clash, or port 5000 where 15721 was suggested instead.

Fix

Section titled “Fix”

  1. Upgrade cc-switch to the latest version first. The crash with the proxy on was fixed in v3.9.1, and the Windows black screen was fixed in v3.9.0+ by switching to the system title bar; a maintainer suggested upgrading to v3.12.3 to verify.

  2. If cc-switch freezes or crashes when Claude Code / Codex / Gemini CLI makes a request with the local proxy on, turn the proxy off to confirm. Once confirmed proxy-related, upgrade to v3.9.1 or newer. On port 5000, try 15721 instead; on port 7890 clashing with Clash, pick another port.

  3. For a white screen on Windows, confirm the WebView2 Runtime is installed. If you fully uninstalled Edge, WebView2 may be missing — install WebView2RuntimeInstaller.exe and retry.

  4. If a white screen or crash on Windows survives the upgrade, delete the .cc-switch folder in your user directory, uninstall, and reinstall. If it persists, back your data up, clear the related files, and reinstall.

  5. If you downgraded from v3.9.* to v3.8.3 and it crashes, restore the cc-switch.db you backed up earlier. Otherwise prefer the newer version over downgrading.

  6. For a white screen, freeze, or failure to start on Linux, prefer the distro-specific package shipped from v3.9.0+; on Fedora try the rpm. If the white screen happens in VMware, turn off virtual machine hardware acceleration.

  7. On an older macOS (10.15 Catalina or macOS 11) showing a white screen, failing to start, or reporting it is unsupported: Tauri 2 demands a recent OS and WebKit, so use cc-switch-cli instead: https://github.com/SaladDay/cc-switch-cli

  8. If cc-switch will not start on Windows because of a misconfigured WSL path or similar, uninstall thoroughly with a tool such as Geek Uninstaller, clear C:\Users\<username>\AppData\Local\com.ccswitch.desktop, and reinstall. Back important data up first.

  9. For occasional crashes while running in the background, collect the logs under .cc-switch/log or .cc-switch/logs and send them to the maintainers. Some of the tao event-loop crashes in this cluster have no stated fix version.

Affected Versions

Section titled “Affected Versions”
Toolcc-switch
VersionUnknown
PlatformsWindowsmacOSLinux

Source Issues

Section titled “Source Issues”

This page is distilled from 20 real issues

FAQ

Section titled “FAQ”
It only crashes with the proxy on and behaves normally with it off. Why?
A panic while the proxy layer handles a request, common around v3.9. Upgrading to v3.9.1 or newer fixes it. Also avoid port conflicts with tools like Clash — change port 5000 to 15721, or move off 7890, if needed.
Windows shows a white screen every time. What now?
Install or repair the WebView2 Runtime first, especially if Edge was ever uninstalled. Then upgrade to v3.2.0 or newer. If that does not help, delete .cc-switch in your user directory and reinstall.
An old Mac says it is unsupported or opens to a white screen. What now?
Tauri 2 demands a recent macOS and WebKit, so 10.15/11 and similar may not render properly. Use cc-switch-cli instead: https://github.com/SaladDay/cc-switch-cli
Linux shows a white screen or freezes after input. What now?
Use the distro-specific package shipped from v3.9.0+ — on Fedora, try the rpm. VMware users can turn off hardware acceleration. AppImage/Flatpak may still fail in some environments.
It crashes after downgrading from v3.9.* to v3.8.3. What now?
Downgrading after running v3.9.* requires restoring the cc-switch.db you backed up earlier. Otherwise upgrade rather than downgrade.
It quits by itself after running in the background for a while and the log shows a tao error. How do I fix it?
Those crashes relate to the Windows event loop, and the issues name no definitive fix version. Upgrade to the latest version, and if it still reproduces, submit the logs under .cc-switch/log or .cc-switch/logs.
Section titled “Related problems”
EGL_BAD_PARAMETER white screen error - cc-switchInstall the native .deb or AUR package instead, or run the AppImage with LD_PRELOAD pointing at the system library, to resolve the ABI conflict.6 issues mergedcc-switch config not applied / not picked up after switching - Claude CodeConfirm the app actually reads the config path cc-switch writes to, then check routing and plugin toggles, duplicate keys, and version compatibility.28 issues mergedError in .codex cc-switch.db causes cc-switch startup failureClose cc-switch, clean records with empty base_url in cc-switch.db, or delete the database file and restart.1 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.