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.

361 topic pages · distilled from 1728 real issuesHow these numbers are calculated

Paste your error message to search…⌘K

Common problems

CC Switch local proxy failed while handling43Codex config.toml configuration lost after switching provider40502 Bad Gateway Codex proxy takeover overwrites config.toml29cc-switch config not applied / not picked up after switching - Claude Code28cc-switch local proxy: 502 Bad Gateway, timeouts, cannot delete a provider26cc-switch import / cloud sync failures: foreign keys, read-only database, overwrites25Codex API key automatically modified leading to model xxx not found24CC Switch config import / sync not taking effect23

By error codeStatus codes, error codes, exception names — match the key fragment from your error output66 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 terminal129 topic pages