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 2 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”
bash: cannot set terminal process group - cc-switchA known 3.18.0 bug when checking the local proxy environment on Linux. Downgrade below 3.18.0 and configure the proxy in the terminal by hand.5 issues mergedcodex cli failed - CC SwitchUpgrading cc-switch to v3.16.3 or newer fixes the local environment detection and the blocked upgrade path.2 issues mergedClaude Code errors or model mapping fails with the CC Switch proxy onUpgrade to v3.15.0 or newer, then set the global outbound proxy explicitly in cc-switch so a stale system proxy cannot be cached by an old process.21 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.