Skip to content
CC Switch WikiUnofficial Community Wiki

not installed or not executable - CC Switch detection failure

Quick fix

Upgrade CC Switch to v3.16.2+, or set the CLI install directory by hand in settings, and clear noise printed by your shell at startup.

Symptom

Section titled “Symptom”
Error output
本地存在 ClaudeCode 和 Codex 环境，但在 CCS 中提示：not installed or not executable
English translation

ClaudeCode and Codex exist locally, but CCS reports: not installed or not executable

Cause

Section titled “Cause”

The CLI tool detection in older CC Switch covered too little and could not recognise Claude Code, Codex, or Gemini CLI installed through fnm, nvm, Homebrew, servbay, a third-party Node version manager, or an unusual Windows path — so the UI showed not installed or not executable. On a Chinese-language Windows system, path encoding can also come back garbled, distorting the detection further.

Another variant is noise printed during shell startup that looks like a version number: ~/.zshrc printing PATH, OSC escape sequences from terminal shell integration, a Node version manager notice, or neofetch output. The old parser mistook digits in that noise for the tool version, so every tool showed the same wrong version or detection misbehaved.

Fix

Section titled “Fix”

  1. Upgrade CC Switch to v3.16.2 or newer. Maintainers confirmed v3.16.0 / v3.16.1 rewrote CLI tool detection to probe PATH, Homebrew, npm/pnpm/bun/volta/fnm/nvm, scoop, WinGet, Windows native paths, WSL, and other sources.

  2. If it is still not recognised after upgrading, set the install directory for codex, gemini, and other CLIs by hand in CC Switch settings.

  3. If the detection shows an obviously wrong version number, check whether ~/.zshrc, ~/.bashrc, ~/.zprofile, or terminal shell integration prints anything containing a version number at startup. Comment that output out temporarily and detect again.

    ~/.zshrc
    # 注释会在 zsh 启动阶段打印版本号或 PATH 的语句，例如：
    # add_to_path "$JAVA_HOME/bin"

  4. Windows users hitting a permissions problem can try right-clicking and running CC Switch as administrator.

Affected Versions

Section titled “Affected Versions”
Toolcc-switch
Version<= 3.16.1
PlatformsWindowsmacOSLinux

Source Issues

Section titled “Source Issues”

This page is distilled from 4 real issues

FAQ

Section titled “FAQ”
Claude Code / Codex / Gemini CLI are installed locally — why does CC Switch still say not installed?
The old detection logic may not cover your install source: fnm, nvm, Homebrew, servbay, or an unusual Windows path. Upgrade to v3.16.2+, or set the install directory by hand in settings.
I installed Node with fnm and cannot see gemini or codex. What now?
Early versions did not support fnm paths. Set the install directory by hand in settings for now; later versions improved probing for fnm and other Node version managers.
Paths come back garbled on a Chinese-language Windows system and detection fails. Why?
A detection anomaly caused by Chinese Windows encoding. Maintainers say it was fixed or implemented among the v3.16.0 / v3.16.1 changes — upgrade to v3.16.1+.
Why does the detected version look like a Java version, a macOS version, or an IP address?
Digits in shell startup output or terminal OSC escape sequences were misparsed as a version by older versions. Clear the startup noise, or upgrade to a version with the hardened parser.
It worked in an earlier version and then stopped reading the environment. Did CC Switch change something?
Users report a fix on Windows for terminals popping up repeatedly, which may have affected the detection method. v3.16.0+ later rewrote CLI tool detection.
Section titled “Related problems”
Claude code does not support gemini - CC Switchcc-switch cannot currently use Gemini as a Claude Code provider — wait for the local proxy feature, or use a third-party proxy project.3 issues mergedA default Gemini config appears and cannot be deleted - CC Switchdefault is the expected provider CC Switch creates by importing your existing live config. Switch the current provider in settings first, then delete it.4 issues mergedHTTP 401 Unauthorized - CC Switch AnthropicUpgrade cc-switch to a fixed build so it sends the x-api-key and anthropic-version headers Anthropic requires.2 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.