cc-switch Troubleshooting Handbook

Unofficial community troubleshooting wiki. It collects the fixes scattered across cc-switch's public GitHub issues into one structured page per problem — each laid out as Symptom / Cause / Fix, with links back to every source issue.

776 topic pages · distilled from 2266 real issuesHow these numbers are calculated

Paste your error message to search…⌘K

Common problems

cc-switch installation, update, and startup issue collection53There's an issue with the selected model42cc-switch import / cloud sync failures: foreign keys, read-only database, overwrites34Opening cc on Windows 11 gives a process but no window - cc-switch31'claude' is not recognized as an internal or external command31Codex auth.json overwritten, KEY mix-up, or official login lost30settings.json configuration lost after switching providers (cc-switch)29Configuration Not Applied or Lost After Switching Providers28

By error codeStatus codes, error codes, exception names — match the key fragment from your error output65 error codesBy providerConfiguration problems when connecting DeepSeek, GLM, Kimi, Qwen, Copilot and others15 providersInstall and launchWon't install, won't open, broken after an update, command not found in the terminal213 topic pagesUpdates and guidesSee what changed in each data and content update, plus practical cc-switch troubleshooting guidesUpdated continuously