Skip to content
CC Switch WikiUnofficial Community Wiki

Cannot install or update Codex CC Switch

Quick fix

Upgrade to v3.16.3+ and reinstall/update Codex from 设置 → 关于 (Settings > About); if v3.16.5 still fails, report it with logs.

Symptom

Section titled “Symptom”
Error output
出现无法进行更新和安装的问题
English translation

Updating and installing does not work

Cause

Section titled “Cause”

Maintainers confirm in #3533 that this is a defect in the upgrade chain of older versions: the bare npm reinstall that `codex update` runs first reports success falsely when the platform binary has not landed, so Codex cannot be installed or updated. This is said to be fixed in v3.16.3: Codex was removed from the self-update-first path, and self-healing logic ("runnability check + uninstall and reinstall") was added. But #5163 still reports the same behaviour on v3.16.5, so the fix does not cover every macOS scenario and the two reports contradict each other.

Fix

Section titled “Fix”

  1. Upgrade CC Switch to v3.16.4 or newer.

  2. Open 设置 → 关于 (Settings > About) in CC Switch and reinstall/update Codex.

  3. If v3.16.5 still fails, keep the screenshot and reopen the issue, attaching the specific error message.

Affected Versions

Section titled “Affected Versions”
ToolCodex
VersionUnknown
PlatformsmacOS

Source Issues

Section titled “Source Issues”

This page is distilled from 2 real issues

FAQ

Section titled “FAQ”
Why can it not install or update even on the latest macOS 26.5?
This has nothing to do with the macOS version. #3533 traced it to a defect in the upgrade chain of older CC Switch versions; v3.16.3 added a Codex runnability check and uninstall-and-reinstall self-healing, so upgrade CC Switch first and retry.
Could you provide an entry point for a config path instead?
The issue does not offer such a config path entry point — it still relies on the automatic install/update logic in CC Switch, so you need to wait for a later version or reopen the issue to request one.
Section titled “Related problems”
"event handler is re-entrant" error or startup crashUninstall Windows update KB5081263 or wait for cc-switch upgrade to avoid crashes and UI rendering failures caused by TAO EventLoop re-entry.2 issues mergederror code is 2503 or icon turns white after upgradeRemove Icon="ProductIcon" from per-user-main.wxs to fix install errors and missing icons. Existing users must unpin and repin.2 issues mergedSymlink target not found: .DirIcon broken symlink causes - CC SwitchAppImage install fails due to broken .DirIcon symlink. Fix by converting it to a relative path.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.