How to troubleshoot cc-switch with this wiki

When cc-switch fails, the fastest starting point is not a paraphrase. Copy the exact error output from the terminal, log, or dialog.

1. Start with the exact error

Paste the complete error into the homepage search. Pagefind indexes the plain-text symptom, issue titles, and page content, so status codes, file paths, environment variables, and fields such as content[].thinking are directly searchable.

If there is no clear error message, use one of the indexes:

• By error code for HTTP status codes, exception names, and fixed error phrases.
• By provider for DeepSeek, GLM, Kimi, Qwen, Copilot, and other integrations.
• Install and launch when the app will not install or open, shows a blank window, crashes, or is missing from the terminal.

2. Match the Symptom first

Every topic page starts with the original symptom. Compare it exactly, especially:

• the error code;
• file names and paths;
• whether the client is Claude Code, Codex, or another tool;
• the operating system and cc-switch version listed on the page.

Similar symptoms do not guarantee the same root cause. If they do not match, do not apply the Fix blindly.

3. Read the Cause

Cause explains the mechanism behind the failure. It helps identify whether the problem is in the provider API, local proxy, configuration synchronization, client cache, or operating-system environment.

Understanding that layer avoids high-cost trial and error such as deleting the database, reinstalling everything, or clearing all configuration.

4. Test one Fix at a time

Follow the steps in order and retest after each change. Back up configuration files before editing and keep a rollback copy. Do not change the provider, endpoint, model, and proxy settings all at once, or you will not know which change worked.

5. Verify against Source Issues

Each topic links to real GitHub issues. Open Source Issues when a step differs from your current version, the page says the problem remains unresolved, or your environment is materially different. Maintainer replies and later comments are the final context.

For one-off reports that still received useful discussion, check More solved problems.