Skip to content
CC Switch WikiUnofficial Community Wiki

cc-switch white screen / black screen / crash / no window on launch

Quick fix

Work out whether it is corrupt window state, a WebView2/OS compatibility problem, or security software. Handle per symptom; use the CLI build if needed.

Symptom

Section titled “Symptom”
Error output
either event handler is re-entrant (likely), or no event handler is registered (very unlikely)

Cause

Section titled “Cause”

This cluster holds several distinct launch failures: a white or black screen after start, a process that exists with no window, nothing happening on a double click, an immediate crash after launch, and tao event-loop errors in the crash report. They do not share one root cause.

The mechanisms confirmed in the issues: 1) the Tauri window state file has stored a nonsensical size (width: 2, height: 2), so the window is invisible on the next launch; 2) on Windows, the WebView2 or OS version, or security software such as 天锐绿盾, IP-Guard, or Astrill VPN, conflicts with Tauri/WebView2, so window creation fails or the screen goes white; 3) older versions had a titleBarStyle Overlay compatibility problem under Windows WebView2; 4) maintainers repeatedly noted Tauri 2 is demanding about the environment, and some older or locked-down systems simply will not start, where the CLI build is worth considering. Some users solved certain WebView2 white screens by setting WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--no-sandbox, but reports are inconsistent.

Fix

Section titled “Fix”

  1. If Task Manager shows a CC Switch process with no visible window, quit CC Switch completely, then check whether the window state file has stored a nonsensical width and height.

    C:\Users\<用户名>\AppData\Roaming\com.ccswitch.desktop\.window-state.json
    # 将 width 和 height 从异常值（例如 2 x 2）改为正常尺寸，如 1200 x 800 后重新启动
    {
      "width": 1200,
      "height": 800
    }

  2. If the screen is white after launch and you suspect a WebView2 or security software conflict, try setting the system environment variable WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS to --no-sandbox and restarting the machine. Note this only helped in some WebView2 conflict cases in the issues, not every white screen.

  3. If enterprise security software (天锐绿盾, IP-Guard and similar) or VPN software is installed, try temporarily disabling or uninstalling it before launching cc-switch, or start cc-switch first and the security software afterwards.

  4. If the problem is on an older Windows or macOS and none of the above helps, update the OS. One user recovered after updating Windows to 24H2. If it still will not start, use the community CLI build: https://github.com/SaladDay/cc-switch-cli

Affected Versions

Section titled “Affected Versions”
Toolcc-switch
Version3.8.2 - 3.16.2（语料中报告过的最高版本）
PlatformsWindowsmacOSLinux

Source Issues

Section titled “Source Issues”

This page is distilled from 14 real issues

FAQ

Section titled “FAQ”
It still will not start after deleting the .cc-switch directory. What now?
Users report deleting the directory is not always enough — a thorough uninstall/cleanup tool may be needed to clear registry entries or leftover config before reinstalling. If the log says database is locked, also confirm no leftover CC Switch process is holding the database.
Does WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--no-sandbox always work?
No. Some users solved a white screen with it and others reported no effect. It targets WebView2 security policy or sandbox conflicts specifically and is not a general fix.
There is a process in Task Manager but no visible window. Has it crashed?
Possibly the window state file recorded a nonsensical size such as 2×2 pixels. Kill the process, edit width/height in .window-state.json, and launch again.
The GUI never opens. Is there an alternative?
Maintainers suggest the CLI build across several issues: https://github.com/SaladDay/cc-switch-cli, especially where Tauri 2's environment requirements stop the GUI from starting.
Is a crash when clicking Settings > About also a launch crash?
Not strictly, but users on WSL/Linux/macOS report the About page freezing or crashing. It is related to the white-screen/crash cluster but has a different root cause.
Section titled “Related problems”
Every click first pops up the system folder picker - cc-switchEdit src/App.tsx to remove the pickDirectory() call in handleOpenTerminal, so opening a terminal stops forcing a folder picker.3 issues mergedBash(...) Waiting... Claude CodeDowngrade Claude Code to v2.1.104 or v2.0.64 (admin required), or switch to a compatible provider such as Alibaba Cloud Bailian.1 issues mergedOnly 258k context in codex - CodexOnce cc-switch maps a minimax model onto gpt-5.5, the hard-coded Codex and Claude Code context limits apply and the 1M context is lost.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.