cc-switch update check fails / update install fails
Quick fix
Usually insufficient permissions or GitHub network trouble. Install as administrator or use the portable build, or download manually from GitHub Releases.
Symptom
Section titled “Symptom”windows的cc-switch检查更新失败The cc-switch update check fails on Windows
This cluster holds several update problems with different root causes:
1. The automatic update check at startup can fail on the GitHub network, the updater manifest, the signature manifest, or the plugin environment. Older versions surfaced "update check failed" as a user-visible error even when you were already on the latest version. Later versions no longer interrupt on a failed automatic check, and fall back to opening the GitHub latest release page when a manual check fails. 2. Installing or updating into a protected directory on Windows such as C:\Program Files\CC Switch fails when the installer has no administrator rights, because the target directory is not writable. A maintainer recommends the LocalAppData default install directory that needs no elevation, administrator mode, the portable build, or the CLI build. 3. On Linux, installing a new version over an old one can leave the in-app version number showing the old value — the version information is not updated correctly after an overwrite install. Uninstalling and reinstalling restores it. 4. On macOS, brew tap farion1231/ccswitch may report MacOSVersionError. The issue record shows this was swept up in a later cleanup, without a stated mechanism. 5. In the tools panel, the "latest version" for Hermes can be lower than the version installed locally, because detection reads PyPI while Hermes mainline moved to git/GitHub releases and PyPI lags behind. This is not a cc-switch update failure but an inconsistent version source for a third-party tool.
If an update or install fails on Windows, first check whether the install directory is a permission-requiring path such as C:\Program Files\CC Switch. If so, uninstall and reinstall into the LocalAppData default directory that needs no elevation, or use the portable or CLI build.
If you must install into a protected directory, run the installer in administrator mode.
If startup reports an update check failure while you are already on the latest version, upgrade to a cc-switch version containing the fix. Newer versions no longer surface a failed automatic update check as a user-visible error.
If clicking check-for-updates by hand fails, open the GitHub Releases page directly to confirm and download the latest version rather than relying on the built-in updater.
If the in-app version number still shows the old value after an overwrite install on Linux, uninstall the current version completely and install the new one.
If Hermes shows a "latest version" below your current one, that is PyPI version detection lagging. Go by GitHub Releases / git tags, or wait for cc-switch to detect via the GitHub Releases API.
Affected Versions
Section titled “Affected Versions”Source Issues
Section titled “Source Issues”This page is distilled from 17 real issues
- #63加一个 cc switch 程序的自动更新功能
- #218一个长久以来的问题
- #476windows的cc-switch检查更新失败
- #481失败
- #633Bug: 覆盖安装后软件内版本号显示不正确
- #1002【功能】通用配置更改自动更新站点配置
- #1064新版本的macOS系统，执行 brew tap farion1231/ccswitch 提示 MacOSVersionError
- #1147测试模型的按钮为什么要取消掉呢
- #1175新版本v3.11.0咋没有模型测试呢
- #1178新版本 3.11 会污染用户强制修改的 setting.json 这不是默认行为，降级后解决
- #1256那个大聪明测试连接的地址删了，无语了，怎么好用的功能，我调试本地服务没跑通，更新版本直接没了
- #1498ccs我记得以前有一键安装和检测codex和Claude的功能新版本是没有了吗
- #1654webdav恢复报错
- #1750最新版本安装错误
- #1818技能仓库的github链接技能没有加载出来，而且还需要自动更新skill的功能
- #4373feat: Claude Desktop 增加关闭自动更新设置
- #6618Hermes 最新版本显示 0.19.0 但本地已安装 0.20.4（PyPI 滞后于 git 主线）
- I am already on the latest version — why does it still say the update check failed?
- Older versions showed a failed automatic startup update check straight to the user; it can be triggered by the GitHub network, the updater manifest, the signature manifest, or the plugin environment. Later versions no longer raise a user-visible error for a failed automatic check.
- Installing the latest version fails on Windows. What now?
- Usually the target directory is not writable. Run the installer in administrator mode, use the portable or CLI build, or uninstall and reinstall into the LocalAppData default directory that needs no elevation.
- The update failed without elevation — the msi progress bar completes then vanishes, and reopening still shows the old version. What now?
- A maintainer explained the default install directory was changed to the LocalAppData path that needs no elevation. Uninstall the old version and reinstall; your data is not lost.
- The in-app version still shows the old number after an overwrite install. What now?
- That is version information not updating correctly after an overwrite install on Linux. The stopgap is a full uninstall followed by a reinstall.
- brew tap farion1231/ccswitch reports MacOSVersionError on macOS. What now?
- That issue was closed in a later cleanup, with maintainers saying it was fixed or superseded by the latest version. If a new version still reproduces it, report back with the version number, system environment, reproduction steps, and logs.
- Hermes shows latest version 0.19.0 while 0.20.4 is installed locally. Is the cc-switch updater broken?
- No. Hermes latest-version detection reads PyPI, while Hermes mainline moved to git/GitHub releases distribution and PyPI lags behind, so the latest can appear lower than your current version. Go by GitHub Releases / git tags.
- Can Claude Desktop auto-update be turned off?
- The related issue in this cluster is a feature request: a disableAutoUpdates toggle for Claude Desktop on the settings page. It is still open/stale and not confirmed implemented.
Related problems
Section titled “Related problems”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.