Skip to content
CC Switch WikiUnofficial Community Wiki

macOS cc-switch version detection error / freeze

Quick fix

Modify the fastfetch call in .zshrc to add a [[ -t 1 ]] check for non-interactive output.

Symptom

Section titled “Symptom”
Error output
mac 版本在检查到新版本后，点击按钮更新之后每次都会卡死。
English translation

After detecting a new version, clicking the update button causes the Mac app to freeze every time.

Cause

Section titled “Cause”

On macOS, cc-switch runs `zsh -lic` to detect tool versions (such as Codex/Claude Code). If your shell config file (e.g., ~/.zshrc) contains commands that execute unconditionally (like `fastfetch`), these may output extra information to stdout when a non-interactive subshell starts (e.g., system version numbers or ASCII art).

cc-switch uses `.find()` to get the first version string. When tools like `fastfetch` output a version number before the actual CLI tool (e.g., mistakenly identifying macOS system version `15.7.9` as the tool version), the frontend thinks the current version is higher than the latest remote version, causing the UI to show "Ready" and the upgrade button to miscalculate. Additionally, some users report the client freezing during this process.

Fix

Section titled “Fix”

  1. Open the terminal and edit your zsh configuration file.

    ~/.zshrc

  2. Find lines calling fastfetch (or other commands that may output text) and prepend a conditional check `[[ -t 1 ]] &&` to ensure it only executes in a genuine interactive terminal.

    ~/.zshrc

Affected Versions

Section titled “Affected Versions”
ToolClaude Code / Codex / Gemini CLI
Version3.16.2 - 3.18.0
PlatformsmacOS

Source Issues

Section titled “Source Issues”

This page is distilled from 16 real issues

FAQ

Section titled “FAQ”
Why does this issue not occur on other platforms?
This issue primarily stems from the default behavior of the macOS zsh shell and interference from specific plugins (like fastfetch) outputting data in non-interactive environments. Windows (PowerShell/CMD) and Linux shell environments typically do not inject such metadata into the version detection pipeline in the same way.
Are there other causes for version detection errors besides fastfetch?
Yes. Any command in ~/.zshrc, ~/.bash_profile, or ~/.profile that executes unconditionally and outputs strings containing version numbers can cause this problem. Check if similar tools like neofetch, screenfetch, or custom scripts are outputting large amounts of text at startup.
Section titled “Related problems”
error code is 2503: CC Switch installation failureWhen error code 2503 occurs, try the NSIS -setup.exe installer; this issue thread does not confirm that the method works.2 issues mergedCC Switch flashes once when clicking any buttonOn Windows, use WebView2 152.0.4191.62 Fixed Version only for CC Switch to avoid click flashing with WebView2 153.0.4234.32.2 issues merged"Failed to upload "image.png"" screenshot upload failedThis is not a cc-switch error. GitHub failed to upload the screenshot. Re-upload it or paste the error as text so maintainers can see it.10 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.