Skip to content
CC Switch WikiUnofficial Community Wiki

error code is 2503 or icon turns white after upgrade - CC Switch

Quick fix

Remove Icon="ProductIcon" from per-user-main.wxs to fix install errors and missing icons. Existing users must unpin and repin.

Symptom

Section titled “Symptom”
Error output
The installer has encountered an unexpected errorinstalling this package. This may indicate a problem withthis package. The error code is 2503.

Cause

Section titled “Cause”

This issue stems from a WIX MSI packaging defect in CC Switch 3.19.0. The template src-tauri/wix/per-user-main.wxs sets Icon="ProductIcon" for desktop and Start menu shortcuts, forcing Windows Installer to cache icons in %APPDATA%\Microsoft\Installer\{ProductCode}\. Since builds use Product Id="*" (generating a new ID each time) and MajorUpgrade is enabled (uninstalling the old version first), the old cache directory is cleared during upgrades. Path resolution or permission conflicts during the new installation throw error code 2503. Taskbar-pinned .lnk files are not protected by MSI component updates; upon restart, the system rebuilds the icon cache, but since the original file path no longer exists, it displays as a blank default icon.

Fix

Section titled “Fix”

  1. Open the src-tauri/wix/per-user-main.wxs file in your project source code and locate the desktop shortcut definition line.

    src-tauri/wix/per-user-main.wxs
    <Shortcut Name="CC Switch" Directory="DesktopFolder" Icon="ProductIcon" ... />
    <Shortcut Name="CC Switch" Directory="DesktopFolder" ... />

  2. Delete the Icon="ProductIcon" attribute from the other Start menu shortcut entry in the file, save, and re-run the build command to generate a new MSI package.

  3. Users with the old version installed should right-click the blank icon on the taskbar and select 'Unpin from taskbar'. Then, run the new MSI to complete the upgrade and pin the app to the taskbar again.

Affected Versions

Section titled “Affected Versions”
Toolcc-switch
Version3.19.0
PlatformsWindows

Source Issues

Section titled “Source Issues”

This page is distilled from 2 real issues

FAQ

Section titled “FAQ”
Why is the NSIS installer (setup.exe) unaffected?
The NSIS installer does not rely on the Windows Installer ProductCode mechanism to manage shortcut icons, so it will not accidentally delete icon cache files during upgrades.
Will damaged taskbar icons automatically recover after the fix is released?
No. This fix only prevents the issue in new versions. For affected users, the .lnk files contain hardcoded invalid paths. You must manually 'unpin -> repin' once to read the correct icon from the new exe.
Section titled “Related problems”
codex cli failed - CC SwitchUpgrading cc-switch to v3.16.3 or newer fixes the local environment detection and the blocked upgrade path.2 issues mergedCannot install or update Codex CC SwitchUpgrade to v3.16.3+ and reinstall/update Codex from 设置 → 关于 (Settings > About); if v3.16.5 still fails, report it with logs.2 issues mergedCannot query usage for an official subscription in the Codex UI - CodexEnable local route mapping so specific models are counted. Third-party APIs need their own query script; Claude official and Free accounts are unsupported.8 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.