Skip to content
CC Switch WikiUnofficial Community Wiki

Troubleshooting cc-switch Upgrade Failures, Freezes, and Display Corruption

Quick fix

Upgrade cc-switch: v3.16.3+ fixes update freezes, v3.20.0+ detects winget-installed Claude Code, and v4.0 refactors upgrades. Upgrade winget installs manually.

Symptom

Section titled “Symptom”
Error output
在cc-switch gui界面中，设置→关于中，3.16.1版本能看到winget安装的Claude code但是升级失败，手动升级winget安装的Claude code并升级cc-switch到3.16.3之后，看不见Claude code了
English translation

In the cc-switch GUI, under Settings → About, version 3.16.1 could detect winget-installed Claude Code, but the upgrade failed. After manually upgrading the winget-installed Claude Code and upgrading cc-switch to 3.16.3, Claude Code was no longer visible.

Cause

Section titled “Cause”

This issue cluster contains several upgrade- and UI-related failures. First, from v3.16.1 through v3.16.3, cc-switch could not correctly detect Claude Code installed through winget at %LOCALAPPDATA%\Programs\claude, causing upgrades to fail or Claude Code to disappear after an upgrade. Earlier versions supported only npm installations; winget detection was added in v3.20.0, and v4.0 further improved upgrade prompts for native, non-npm installations. Second, on macOS, the interface could freeze after users clicked update, and the update appeared complete only after force-quitting. The old download-install-restart flow depended on WebView continuing to run JS after the application bundle was replaced, which could deadlock. v3.16.3 fixed this by moving the flow to the backend (install_update_and_restart). Other issues include display corruption on Windows, possibly related to reinstallation after disk damage, with the relevant functionality refactored in 4.0; the interface freezing when editing providers on Ubuntu, a bug introduced by the v4.0.11 UI refactor; and duplicate Dock icons after online upgrades on macOS in v4.0.10-v4.0.12.

Fix

Section titled “Fix”

  1. Upgrade cc-switch to the latest version, preferably v4.0 or later, to get winget installation detection, update-flow improvements, and fixes from the UI refactor.

  2. For Claude Code installed through winget, upgrade it manually with: winget upgrade Claude.Code (or consult the official Claude Code documentation).

  3. If an update freezes on macOS, use v3.16.3 or later. The update flow now runs in the backend, so force-quitting is unnecessary.

  4. If the problem persists, such as editing freezing on Ubuntu or duplicate Dock icons, report it in a GitHub issue with the cc-switch version, OS version, installation path, and error details.

Affected Versions

Section titled “Affected Versions”
Toolcc-switch
Version3.16.1 - 4.0.12（部分问题在 v3.16.3、v3.20.0 或 v4.0 修复）
PlatformsWindowsmacOSLinux

Source Issues

Section titled “Source Issues”

This page is distilled from 5 real issues

FAQ

Section titled “FAQ”
Why can't cc-switch find my winget-installed Claude Code?
Before v3.20.0, cc-switch supported only npm-installed Claude Code. Upgrade to v3.20.0 or later and ensure Claude Code is installed at %LOCALAPPDATA%\Programs\claude.
What should I do if the interface freezes after clicking update on macOS?
This is a known issue in versions before v3.16.3, caused by an update-flow deadlock involving WebView. Upgrade to v3.16.3 or later, where the update flow runs in the backend.
How can I fix display corruption or freezing after upgrading cc-switch, such as when editing a provider on Ubuntu?
Display corruption may depend on the system environment. Upgrade to v4.0 or later, which refactored the relevant functionality. The Ubuntu editing freeze is a known v4.0.11 bug; follow GitHub issue #8302 for progress.
What should I do if two icons appear in the Dock after an online upgrade on macOS?
This is a known issue in v4.0.10 through v4.0.12. Follow GitHub issue #8329 for progress, or try reinstalling cc-switch.
Section titled “Related problems”
Codex CLI failure: CC SwitchUpgrade cc-switch to v3.16.3 or later to fix blockers in local environment detection and the upgrade flow.2 issues mergedCodex conversations with third-party models frequently stop automaticallycc-switch loses function call name/call_id during Responses API conversion. Connect DeepSeek directly to Codex, or upgrade cc-switch and retest.7 issues mergedOfficial account balance information suddenly missing in CodexUpgrade to the latest version, which reworked quota display in 4.0, and check again. If it is still missing, provide the version, login method, plan type…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.