Install and launch problems
Won’t install, won’t open, broken after an update — all of it is here.
213 topic pages, distilled from 731 real issuesHow this is counted
Terminal and environment variables136
Opening cc on Windows 11 gives a process but no window - cc-switchOn Windows 11, try Windows 7 compatibility in the exe properties. If that fails, use cc-switch-cli to bypass the Tauri 2 GUI white screen.'claude' is not recognized as an internal or external commandConfigure the full claude.exe path in CC Switch settings, or ensure claude is on the system PATH.cc-switch Local Proxy FAQ: 502 Bad Gateway, Timeouts, Unable to Delete ConfigurationsProxy issues often stem from unsupported official providers, unapplied settings, or unsynchronized UI state;'claude' is not an internal or external command, nor a runnable programUpgrade to v3.16.2+ to fix WSL/Windows path detection, or manually configure install directory override.The `content[].thinking` in thinking modeSome variants remain unresolved: upgrade to a version with the thinking history normalization fix; for Codex routed through DeepSeek, use a version with the…Upstream Chat Completions Streaming Response Error, Claude CodeCheck whether the issue is caused by local proxy conversion or the upstream endpoint; adjust the endpoint or disable the local proxy for the verified scenario.Switching providers resets claude settings.json - Claude CodeBefore switching, extract the current provider’s configuration in “General Configuration” and select “Write to General Configuration” for the new provider.MCP stdio connection failure: cmd /c wrapper prevents Claude Code from connectingOn Windows, if editing MCP configuration introduces a cmd /c wrapper and causes connection failure, check the generated command and args, then upgrade to a…EGL_BAD_PARAMETER: CC Switch White Screen on LinuxFor affected Linux AppImage environments, preload the host libwayland-client first. If the white screen remains, try the .deb package.Not logged in · Run /login - Claude CodeTurn CC Switch local proxy takeover on, check the API address includes /v1, or launch the terminal from CC Switch so env vars are injected.Claude Code Auth conflict errorRemove primaryApiKey from ~/.claude.json or add "auth_mode": "bearer_only". Restore overwritten settings via default or manage shared settings with Common…env: node: No such file or directoryWhen CC Switch is launched from the Dock/Finder, the GUI PATH lacks the Homebrew directory; upgrading to v3.18.0+ fixes it.Unexpected status 502 Bad Gateway：CodexSet `NO_PROXY=127.0.0.1,localhost,::1` in `~/.codex/.env` so Codex connects directly to the local CC Switch port.Atomic replace failed — request not supported, os error 50 - cc-switchUpgrade cc-switch to v3.20.0 or newer, which fixes the regression where atomic config file replacement failed on WSL paths.Provider API Key Overwritten: After Codex Restart or SwitchUpgrade to cc-switch v4.0.0 or later to prevent provider keys from overwriting each other and restore the official login state.model does not support thinkingTurn the Proxy Rectifier off in cc-switch advanced settings, or upgrade to a fixed version. Qwen tool call loops and empty thinking blocks remain unresolved.auto mode cannot determine the safety: Claude Code errorUpgrade CC Switch first. If the error persists, check thinking parameters, model mapping, stop support, and the response format when stream is omitted.Kaspersky virus detection deletes ccswitch — Gemini CLIAdd CC Switch to the security allow list in Windows security software, then use Gemini CLI.Codex/OpenCode shows not installedAdd the npm prefix or fnm alias directory to the user PATH environment variable, then restart CC Switch.either event handler is re-entrantOn Windows, try WebView2 parameters if enterprise security software conflicts; the reports provide no generally verified fix.INVALID_API_KEY after switching providers in CodexUpgrade to v3.20.1 or later; third-party switching no longer writes to `auth.json`, preventing provider key/authentication mismatches.Restarting the terminal and running gemini asks for an api-key - Gemini CLIUpdate cc-switch for the save-clears-config bug. If it still fails, that is a Gemini CLI read bug — put the environment variables in bash_profile.Relay Link Speed Test Fails Without VPN - CC SwitchNo single confirmed fix is available. Provide a reproducible configuration, request target, and startup logs.WSL path configured but skills are not read - cc-switchWindows cc-switch cannot read or install WSL ~/.agents/skills. Install and run the Linux build of cc-switch inside WSL instead.API Error: 404 - Claude Code path assembly or unregistered routeCheck whether the API address was assembled wrongly, or upgrade cc-switch for the 404 from OpenAI-compatible mode and the missing local route.Not installed / not installed or not executable - CC SwitchUpgrade CC Switch to v3.20.0+ for custom npm prefix and macOS detection failures; the false "several installations" on Windows needs v3.16.5+.System folder picker opens on every click cc-switchRemove the pickDirectory() call from handleOpenTerminal in src/App.tsx to stop the folder picker from opening whenever you click to open a terminal.zsh:1: command not found: claudeUpgrade cc-switch to v3.16.4 or newer, fixing PATH not loading when the terminal launches, or switch to the system default terminal for now.auth.json not updated after switching channelCodex authentication mechanism refactor causes switching to fail. Check auth.json path and configuration per the official authentication retention guide.env: node: No such file or directoryUpgrading cc-switch to v3.18.0 or newer fixes the environment variable resolution failure caused by a stripped PATH in the GUI.Invalid type for 'messages'Upgrade cc-switch to the latest version for the conversion fix, or downgrade the Codex CLI to 0.80.0 and use wire_api="chat" to work around it.tools.function.parameters is not a validUpgrade to a later version containing #6863; it converts `$ref` with sibling keywords into Moonshot-compatible `allOf`.Cannot import providers, cannot manage sessions - cc-switchUpgrade cc-switch for jsonc config support. Under WSL2, clone the database to a local Windows path on a schedule to work around SQLite locking.not installed or not executable - OpenCodeUpgrade CC Switch to v3.11.0+ for the path detection fix, or symlink opencode into ~/.local/bin by hand.skills synced to apps I did not select - OpenCodeUpgrade cc-switch to v3.12.3 for the implicit inference bug fix, and turn off reading skills from the .claude directory in OpenCode settings.missing field `call_id`: Codex automation HTTP 400No verified published fix is available. Normalize orphaned output without `call_id` during proxy forwarding and retain cross-task message content.Unkonw coding plan provider - cc-switch VolcengineUpgrade cc-switch to v3.20.0 or newer, then recreate the Volcengine Agent Plan provider or fix its Base URL.Failed to authenticate: Claude Desktop gateway token invalid — ClaudeSign out of the stale official account session in Claude Desktop and restart the app. If the error persists, switch to the default provider and then switch…Select Model Menu Still Shows Pre-Switch Model List - CodexClose existing Codex sessions, run `codex app-server daemon restart`, and upgrade CC Switch to v4.0.7 or later for detection and restart prompts.Only 258k context in codex - CodexOnce cc-switch maps a minimax model onto gpt-5.5, the hard-coded Codex and Claude Code context limits apply and the 1M context is lost.codex never shows the ds model - CodexCodex desktop needs an official login state to show third-party models. Enable keep-official-login-when-switching in cc-switch and restart.cc-switch overrides DNS cache and resolvesDisable proxy takeover in the affected application to restore network connectivity; cc-switch does not modify system DNS records.It reports 401 in claude - Claude CodeTurn the cc-switch local proxy on to convert the API format, and make sure `ANTHROPIC_BASE_URL` is injected into the Claude Code process.Error running remote compact task error - CodexUpgrade cc-switch to v3.12.0 or later. It adds forwarding support for the Codex `/responses/compact` route in the local proxy and can resolve 404 or 502 errors.Function call is missingUse the community cc-switch-gemini-fixer patch, or inject skip_thought_signature_validator into history messages, to bypass the signature validation.`GLIBC_2.35' not foundNo confirmed compatible release exists from v3.10.1–v3.16.1. Try v4; if it still fails, report the version and reproduction steps.Gtk-CRITICAL: gtk_widget_get_scale_factor failedOn a GTK assertion failure running cc-switch under Linux or WSL2, edit settings.json to turn silent startup off, or clean the leftovers and reinstall.Not found (404)Upgrade cc-switch to v3.16.3 for the 404 from /v1/ appended wrongly to a Base URL, and enable the media fallback so images cannot trip the breaker.InputValidationErrorWhen long tool arguments are truncated during streaming SSE, temporarily disable Tool Search, maximum-effort thinking, and the 1M declaration, then restart and…Missing API key · Run /login - Claude CodeClear the conflicting ANTHROPIC_BASE_URL environment variable, or upgrade CC Switch to use its built-in environment variable conflict detection.protocol handler not registeredOn Linux, change Exec to cc-switch %U in the CC Switch.desktop file so Chromium browsers recognise the import protocol. For WSL sync, check admin rights.<tool_use_error>InputValidationErrorAn SSE parsing bug in the cc-switch conversion layer loses tool calls. Connect to the API directly, or switch to an official node, for now.Error 2503: CC Switch MSI Installation Fails on Windows 11Open Command Prompt as an administrator and run msiexec /i with the MSI file path.Local Claude CLI installed but Settings says it isn'tUpgrade CC Switch to v3.16.5 or later to fix false installation conflicts and garbled paths on Windows.Symlink target not found: .DirIcon broken symlink causes - CC SwitchAppImage install fails due to broken .DirIcon symlink. Fix by converting it to a relative path.ccstatusline shows the wrong model name - Claude CodeConfigure a Custom Command script in ccstatusline that reads the environment variables from the cc-switch database to show the real model.Opening a terminal does not use the complete configurationExtract through the "shared configuration" panel and tick write, so a full overwrite does not lose plugins and other shared config.session isn't eligibleFor a non-Anthropic upstream or format conversion, set CLAUDE_CODE_AUTO_MODE_SERVER=0 in the provider env.Why is the model the claude command uses in a plain terminal different from the one in cc-switch?Set the MiniMax you want as the primary model and run claude from a cc-switch terminal. Without takeover on, the mapped name is not a substitution.No such file or directory (os error 2)Change the model_catalog_json absolute path in config.toml to the relative cc-switch-model-catalog.json, or upgrade cc-switch.Session expired: Codex OAuth session expiredUpgrade to cc-switch v4.0.0 or later to prevent old snapshots from overwriting new login credentials."Expecting property name enclosed in doubleUpgrade CC Switch to v3.16.4 or newer to fix the JSON parse error caused by a large request body not being decompressed.Function call is missing a thought_signatureUpgrade to the latest CC Switch 4.0 release and retry. If it persists, report the version, system, full reproduction steps, and logs.The Gemini CLI reading the project .env breaks cc-switchWrap the gemini command in PowerShell to load the ~/.gemini/.env environment variables by hand.does not run on macOS versions other than Monterey: CC Switch installation failureRun `brew update` and retry. If the cask is still locked to Monterey, change the macOS condition to `>= :monterey`.invalid_request_error Kimi For CodingSet ENABLE_TOOL_SEARCH=false in the Kimi configuration in cc-switch.KMS: DRM_IOCTL_MODE_CREATE_DUMB failed: Permission deniedResolve cc-switch white screen DRM permission errors on Linux by disabling WebKit hardware acceleration, specifying NVIDIA rendering, or using the CLI version.No endpoints available that support Anthropic - Claude CodeUpgrade Claude Code to v2.1.92+ and update cc-switch to fix OpenRouter parameter errors, or disable the local proxy.not found(404) adding Claude Code desktop model APIUpgrade to v3.16.3+ to fix connectivity detection false positives, or ignore the 404 and test actual calls directly.Windows Explorer opens to the "Documents"On Windows, Open Terminal opens Documents instead of a terminal. A suspected cause and suggested fix exist, but no solution has been verified.Claude Code opens a folder selection dialogThis is by design for selecting the Claude Code terminal working directory; select the relevant project folder, then open the CLI.thinking enabled but reasoning_content missingDisable Thinking mode in Claude Code, or upgrade cc-switch to fix Kimi/Moonshot tool call errors.Unsupported parameter: 'max_tokens'The route forwards max_tokens to a model that only accepts max_completion_tokens. Verify parameter support or wait for a cc-switch fix.'/d' is not recognized as an internal or external command: Claude CodeOn Windows, first avoid choosing a Chinese working directory; the issue is not confirmed fixed, so verify the actual directory after startup.API Error: Connection refusedIn Windows WSL2 NAT mode, use socat to forward WSL's 127.0.0.1:15721 to the host CC Switch routing port.x-anthropic-billing-header breaks caching - CC SwitchUpgrade CC Switch to v3.15.0+, which fixes the dynamic billing header breaking prefix caching in openai_responses mode.ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEYRun `claude daemon stop --any` to stop lingering Claude background processes, then restart and resume the session.Why is the value of ANTHROPIC_BASE_URL empty? Claude CodeThis is expected behavior: CC Switch does not inject variables into the shell; check the current configuration in `~/.claude/settings.json` directly.<thinking> tags output as body text in Claude CodeChanging the provider's apiFormat from openai_chat to anthropic, if supported upstream, can bypass inline <thinking> leakage.Body discarded: Anthropic protocol conversion Claude CodeUpgrade to v3.20.3 or a v4 version containing the fix; the converter ignores trailing empty reasoning_content.Proxy not working, constant reconnect after entering a question; CodexThe separate proxy feature in cc-switch was removed; set the proxy via $env:http_proxy in PowerShell, then run Codex.Incorrect model displayed in Claude CodeConfigure a Custom Command for ccstatusline to read the model name from the current cc-switch provider configuration.“ANTHROPIC_API_KEY or another auth sourceUpgrade CC Switch from 3.16.4 to the refactored 4.0 or later, then retest.Route classifier requests to another provider in Claude CodeThis is an unresolved feature request; the original post provides no verifiable user-side configuration solution.The auto mode classifier is temporarily unavailableDisable the Anthropic Base URL proxy in CC Switch and restart Claude Code; one user in the issue reported that updating CLIProxyAPI resolved the problem.Model automatically switched to haiku cc-switchBuilt-in Claude Code behavior: haiku reads files. cc-switch only manages environment variables and does not change model selection./branch sessions: parent session hard to find in Session ManagerTry claude --resume or claude -r <sessionId> as the proposed workaround. The original post provides no verifiable Session Manager fix.Tool calls in claude cli stream interrupted after configuring a local proxy Claude CodeNo verified solution is available; one user reported switching to claude-code-router as an alternative.Bash(...) Waiting... Claude CodeDowngrade Claude Code to v2.1.104 or v2.0.64 (admin required), or switch to a compatible provider such as Alibaba Cloud Bailian.Claude Code no longer hot-reloads settings.json after switching providersRestart Claude Code after switching so it reads settings.json again; clash-for-ai can avoid this limitation.Open sessions continue using a third-party ANTHROPIC_BASE_URLSet legacy ANTHROPIC_* keys to empty strings in the official provider configuration's env, then switch back to the official provider.Unable to apply reverse proxy to Claude Code VS Code pluginEnable “Apply to Claude Code plugin”; if the old provider is still active, check and remove the previous Zhipu relay settings in VS Code settings.json.Claude Provider Not Found, Unable to Take Over Live Configuration: Claude CodeUpgrade to v4.0 or later; routing logic has been rewritten. Claude Desktop uses model mapping mode, with no manual changes to settings.json needed.请求转发失败: 上游请求失败: client error (Connect)Temporarily bypass the CC Switch local proxy or switch networks to check whether DeepSeek is blocked. No final fix has been confirmed.Claude Code exits whenever the window size changesUpdating the relevant upstream component restored window resizing; the reporter confirmed the upstream update resolved the issue.Format conversion error: No choices in response - CC SwitchClinePass wraps the response in a data envelope, breaking parsing. Upgrade CC Switch to a version with the fix, or use a local proxy to unwrap response.data.After switching, opening codex still uses the old account — CodexAfter switching OAuth accounts, fully restart the Codex background service. For CLI, run `codex app-server daemon stop`, then reopen Codex.auth.json contamination in CodexIn Codex 3.16.0, the official login state remains in auth.json. Check provider, endpoint, and token for BYOK in config.toml.missing field `call_id`DeepSeek Responses rejected a Codex delegated task entry missing `call_id`; the issue did not confirm a user-side fix.missing field `call_id`Clean up orphaned heartbeat output entries when enabling requests through a proxy; this issue did not confirm that CC Switch has a fix.No API key configured for provider: customUpgrade Codex CLI and CC Switch to the latest versions; CC Switch supports reading the Codex CLI version from config.toml.Disabled MCP takes effect again in CodexThis issue currently has no confirmed fix; if the problem persists, reopen the issue to continue tracking.Tool calls always hang: Codex function_call loses call_idA commenter confirmed non-empty id/name checks restore tool calls. The post also suggests bypassing CC Switch Responses translation to connect directly to…There Should Not Be Such a Huge Number of unknown Model Requests — CodexRetest on CC Switch 4.0.13. If many unknown requests remain, reopen the issue with the version, system, reproduction steps, and logs.Copilot subscription model mapping not applied, still calls Claude modelsThis is a known bug in cc-switch v3.14.1. Upgrading to v3.15.0 fixes the issue where Copilot subscription model mapping is not applied.Clicking “Add” has no response, CodexEnter a non-empty `OPENAI_API_KEY` in `auth.json (JSON)` before adding, then change it back to `{}` afterward; the maintainer plans to remove this validation.Sessions may stop responding (JSONL stops being written) — Claude CodeUpdate CC Switch to the latest 4.0 release and retry. If it still hangs, temporarily bypass CC Switch and submit complete reproduction details.“Bash tool is continuously searched for but cannot be loaded or invoked properly” - Claude CodeBypass CC Switch and configure GLM directly in Claude Code; or upgrade to CC Switch 4.0.13 and retest.How to adjust GPT reasoning effort? Claude CodeThe original post did not provide a verifiable adjustment method. Follow subsequent discussion in this issue.Hermes is not detectedThe original report has no verifiable solution; the maintainer merged it into #4162 for tracking.“About” page hangs: Linux cc-switch tool detectionUpgrade to cc-switch 4.0; the maintainer says it substantially changed configuration switching and the interface, and many related problems no longer occur.Cannot set terminal process group: ioctl operationThe original post has not provided a verified fix. Follow Issue #5635 for updates.MCP Configuration Differences Across CLI Tools, CodexThe same MCP service uses different configuration formats and parameters in Codex and Claude; no verified solution has been provided.failed to parse function argumentsNo verified fix is available. Check Codex session logs for truncated arguments JSON, then report it to the upstream provider or switch providers.Effort is silently dropped for all muse-spark-* models in Claude CodeThe issue proposes adding muse-spark to an allowlist, but no verifiable fix is available yet.experimental_bearer_token = "PROXY_MANAGED"Upgrade to CC-Switch v3.16.2 or later. If it persists, sign in to Codex OAuth again and reopen the report as requested.[DISCUSS] Support for pi coding agentThis is a feature request merged into tracking issue #1855; the original post provides no verifiable solution.Model does not respond, Claude CodeDelete all providers, then set the same model for the same provider to restore Claude Code conversations.401 Unauthorized caused by PROXY_MANAGEDUpgrade to 4.0 or the latest version; use the real API key from the provider configuration for routing.unsupported call: — Codex tool call failedNo confirmed fix yet; CC Switch must preserve function_call name and call_id in streaming events.No tool output found for tool callNo official fix is confirmed. The reporter describes a local workaround that reorders tool calls and outputs. Follow the main issue for progress.Cannot start normally: window unresponsive, system requires force quitUpdate CC Switch to 4.0 or the latest version and retry. If it persists, provide the full version, steps, logs, and screenshots.Environment variables not written: VS Code Claude pluginCheck VS Code `settings.json` for Claude environment variables; if present, comment them out and reopen Claude.vscode Claude Code plugin cannot switch configuration immediately - Claude CodeThe VS Code Claude Code plugin cannot use a proxy or hot-switch; start cc from the terminal CLI for changes to take effect immediately.400 model provider error Claude Code pluginAdd the environment variables required by the current provider to VS Code’s claudeCode.environmentVariables setting so the plugin can read them.White flash when switching tabs, CC SwitchThe issue may be related to a WebView2 153.x update. If it continues after upgrading to CC Switch v4.0, provide the version and reproduction steps.Error 2147942402 (0x80070002) — Claude CodeRecheck after upgrading to CC Switch v3.16.1 or later on Windows; temporarily set PowerShell as the preferred terminal.cc-switch keeps opening detection windows when checking local codexWindows CLI detection causes windows and processes to pile up. The issue provides no verifiable fix; a timeout is only a user request.cmd.exe console window flashesUpdate to 4.0 or the latest version and retry. If it persists, submit the version, system details, reproduction steps, and logs or screenshots.Window Size Overflows to 65535×53251, CC Switch Main Window InvisibleFully exit CC Switch, delete the window state file, and restart to clear the persisted invalid window size.Configuration Not Applied: Claude Code WSL Routing Config Not UpdatedSet the configuration directory to the file path used inside WSL in CC Switch Settings > Advanced. If the issue persists after upgrading to 4.0, provide…No models displayed after opening pi - piPoint CC Switch’s Pi configuration directory to the WSL `~/.pi/agent` path. The reporter confirmed that models appeared again.Claude Code verification required when entering ClaudeIn Windows WSL, write the rule that skips Claude Code’s initial confirmation to the corresponding JSON; the maintainer confirmed the issue was fixed.Cannot start cc-switch; cc-switch --version produces no outputThe maintainer recommends reinstalling first; if it still cannot start, try the CLI version. Recovery was not confirmed in the original post.Cannot detect conversation history and usage statistics? Claude CodePoint the Claude configuration directory to the WSL path; route Claude Code in WSL through the cc-switch gateway for usage statistics.3.15.0 hangs on startup under WSLg: CC SwitchRolling back to 3.14.1 restores normal startup; alternatively, reproduce on the latest version and submit WSL, graphics environment, and startup output details.
Update and upgrade52
cc-switch usage query fails / keeps showing failed / undefinedUpgrade to v3.16.2+. If it still fails, fill in base_url and the access token in NewAPI format, or turn off auto-refresh and the usage query.cc-switch update check fails / update install failsUsually insufficient permissions or GitHub network trouble. Install as administrator or use the portable build, or download manually from GitHub Releases.macOS cc-switch version detection error / freezeModify the fastfetch call in .zshrc to add a [[ -t 1 ]] check for non-interactive output.settings.json gets reset - Claude CodeWrite shared fields like plugins and hooks into "Common Config" and check write-back on switching; if takeover mode misbehaves, disable it, switch provider…CC Switch Proxy Fails or Requests Are Blocked by the System ProxySet CC Switch's global outbound proxy to your proxy application's address, or bypass local requests in the system proxy, then restart CC Switch."Failed to upload "image.png"" screenshot upload failedThis is not a cc-switch error. GitHub failed to upload the screenshot. Re-upload it or paste the error as text so maintainers can see it.Codex conversations with third-party models frequently stop automaticallycc-switch loses function call name/call_id during Responses API conversion. Connect DeepSeek directly to Codex, or upgrade cc-switch and retest.Unexpected status 502 Bad Gateway：CodexSet `NO_PROXY=127.0.0.1,localhost,::1` in `~/.codex/.env` so Codex connects directly to the local CC Switch port.Provider API Key Overwritten: After Codex Restart or SwitchUpgrade to cc-switch v4.0.0 or later to prevent provider keys from overwriting each other and restore the official login state.It says 1.6 billion used — usage statistics spiking - CodexUpgrade cc-switch to v3.18.0 to fix the sub-agent history replay double-count bug; it rebuilds the polluted Codex usage data automatically."Not logged in · Please run /login" - Claude CodeUpgrade cc-switch to v3.19.2+, or change ANTHROPIC_API_KEY to ANTHROPIC_AUTH_TOKEN in settings.json by hand to skip the approval prompt.Troubleshooting cc-switch Upgrade Failures, Freezes, and Display CorruptionUpgrade cc-switch: v3.16.3+ fixes update freezes, v3.20.0+ detects winget-installed Claude Code, and v4.0 refactors upgrades. Upgrade winget installs manually.Common Issues After Upgrading cc-switchUpgrade to v4.0 or later; most sync, switching, and display issues from older versions are fixed.Codex Desktop project list disappears or reasoning levels are reduced - CC Switch configuration issueMost related issues remain unresolved. After upgrading CC Switch or switching providers, changes to Codex’s model_provider field can make project history…env: node: No such file or directoryUpgrading cc-switch to v3.18.0 or newer fixes the environment variable resolution failure caused by a stripped PATH in the GUI.502 Bad GatewayCodex/Claude Desktop reports 502 due to CLI proxy conflicts or app-server bypassing proxy. Remove proxy config or downgrade versions to fix.Config changes in the GUI have no effect at allOMO v4.19.3 moved config to ~/.omo/omo.jsonc, so cc-switch writes to a dead path. Edit the new config file by hand, or upgrade cc-switch.Usage query requires same-origin requests in cc-switchIn cc-switch, switch to the generic or custom template and enter the usage query URL directly in the request address to bypass the same-origin restriction."deepseek-v4-flash" is not a modelMost related issues remain unresolved. Upgrade to CC Switch v4, enter the model's actual context window, and use [1m] only if it truly supports 1M.Official account balance information suddenly missing in CodexUpgrade to the latest version, which reworked quota display in 4.0, and check again. If it is still missing, provide the version, login method, plan type…Configuration UI FlickeringUpgrade cc-switch to fix flickering from async form loading; read SQLite DB to fix env vars not updating with providers.IO 错误: 当文件已存在时，无法创建该文件 (os error 183)A Junction/hard link configuration directory causes the error. Use a regular directory temporarily and wait for a cc-switch fix.No skill found in the ZIP file (it must contain a SKILL.md)Upgrade cc-switch to v3.16.2 or newer, and delete the old directory by hand before importing a Skill of the same name.Codex CLI failure: CC SwitchUpgrade cc-switch to v3.16.3 or later to fix blockers in local environment detection and the upgrade flow.[proxy::response_processor] [Claude] stream errorA stream decode error or timeout proxying Claude Code loses logs or records 0 tokens. Fix the model extraction fallback to show the right model.Automatic upgrade fails; reinstalling still shows old Codex versionNo verified solution yet. #3156 suggests uninstalling and reinstalling; #7080's version-detection issue remains unconfirmed.Automatic approval review failedThe CC Switch local proxy received an upstream 403 while handling the Codex /responses endpoint, causing automatic review to fail; no official fix is available.X-OpenAI-Internal-Codex-Responses-LiteComment out the custom provider model_provider setting and return to the built-in openai provider; alternatively, temporarily switch to gpt-5.4.Session expired: Codex OAuth session expiredUpgrade to cc-switch v4.0.0 or later to prevent old snapshots from overwriting new login credentials.KMS: DRM_IOCTL_MODE_CREATE_DUMB failed: Permission deniedResolve cc-switch white screen DRM permission errors on Linux by disabling WebKit hardware acceleration, specifying NVIDIA rendering, or using the CLI version.error code is 2503: CC Switch installation failureWhen error code 2503 occurs, try the NSIS -setup.exe installer; this issue thread does not confirm that the method works.CC Switch flashes once when clicking any buttonOn Windows, use WebView2 152.0.4191.62 Fixed Version only for CC Switch to avoid click flashing with WebView2 153.0.4234.32.Request still uses the old session model, CodexSet all relevant provider configurations in the failover queue to the required model; when continuing an old session, select the target model in the Codex…unexpected status 403 ForbiddenDisable 'Keep Official Login' in CC Switch and restart to stop Codex from sending image gen requests causing 403 errors.total_cost_usd = 0: Claude CodeAdd pricing for claude-opus-5-5 to the model_pricing seed data to prevent imported request costs from being recorded as $0.Not logged in · Please run /loginMove PROXY_MANAGED in ~/.claude.json from the rejected approval list to the approved list, then use routing again.auth.json Is Force-Replaced, Making Codex UnusableUpgrade to a later version that includes the fix. Before upgrading, disable Codex takeover, sign in to official ChatGPT, then re-enable takeover.Codex usage statistics failureAfter Codex updated to 26.917.51856, GPT-6 Sol usage statistics may remain at 0; the issue provides no confirmed fix.[CODEX-SYNC] deferred 4 CodexUpgrade cc-switch to v3.20.3 to fix Windows session files permanently deferred when mtime does not change.Local Codex is up to date, but CC Switch detects an older versionUpgrade to the latest CC Switch, then check the version, install location, and source shown for Codex on the “Applications” page.Cannot set terminal process group: ioctl operationThe original post has not provided a verified fix. Follow Issue #5635 for updates.Unable to fetch modelsAfter upgrading to v3.16.4, fetch models again. If it still fails, add the provider, error text, or logs to the original issue.OpenCode V2 Usage Collection Stops UpdatingUpgrade CC Switch to a version containing the PR #7541 fix so the collector reads OpenCode V2 tables.Fill in the API Key for an unofficial provider - Claude CodeUpgrade to cc-switch 4.0 or later. If the API Key field is still missing, provide the version, provider type, and a screenshot.Requests keep failing after configuring a relay — Claude CodeEnable routing from the top bar, then apply it to Claude. “Enable full URL” does not enable routing. The reporter confirmed this fixed the issue.Optional isolation forced output Claude CodeSet `strict: false` on ordinary function tools during Responses conversion and preserve the existing required fields in `required`.Skill updates silently overwrite local changesBack up local changes before updating; the proposed fix will exclude locally modified Skills from “Update All.”Skills remain as copies after automatic import, CC SwitchAutomatic import copies Skills to `~/.cc-switch/skills/` and does not delete the source directory in `~/.agents/skills/`.Codex key abuse after opening CodexThe original report only describes suspected abnormal calls; no verifiable fix or virus file location was provided.Self-update check fails and latest model versions show as unknown - Claude CodeUpdate CC Switch to the latest version and retry; related functionality was refactored in 4.0, but the fix was not confirmed.Form content is overwritten by the last entry when editing, cc-switchThis was a fixed cc-switch frontend issue; the original post did not state the specific version containing the fix.Claude Code crashes on launchThe original post has not provided a verifiable fix. Follow the subsequent handling in Issue #2923.
Launch crash / blank screen30
cc-switch crashes on launch / white screen / black screen / background crashUpgrade to the latest. Windows white screen: install WebView2. Proxy crash: change port, upgrade to v3.9.1+. Old macOS/Linux: use the CLI or distro package.EGL_BAD_PARAMETER: CC Switch White Screen on LinuxFor affected Linux AppImage environments, preload the host libwayland-client first. If the white screen remains, try the .deb package.either event handler is re-entrantOn Windows, try WebView2 parameters if enterprise security software conflicts; the reports provide no generally verified fix.zsh:1: command not found: claudeUpgrade cc-switch to v3.16.4 or newer, fixing PATH not loading when the terminal launches, or switch to the system default terminal for now.Codex startup failure: missing supports_reasoning_summariesUpgrade cc-switch to v3.18.0 or later, then switch to the DeepSeek provider again to regenerate the model catalog. This automatically fills in the… (Codex)unknown variant `image_url`, expected `text`Do not send images to models that do not support image input. Use text only, or wait for/use the merged automatic retry mechanism that removes images.assertion failedUpgrade cc-switch to the latest version for the underlying GUI framework crash fix, or try closing proxy software and resetting the network.cc-switch on Linux freezes when clicking input fields, UI does not refreshUpgrade to cc-switch v3.13.0 or later. It sets WEBKIT_DISABLE_COMPOSITING_MODE=1 at startup and applies a window focus fix.Could not create default EGL displayOn Linux, cc-switch forces WEBKIT_DISABLE_DMABUF_RENDERER=1, causing a blank window. Set it to 0 before launch to restore the UI.ASProxy64.dll Access Violation Causes CrashAdd cc-switch.exe to Astrill’s Help → Hard excluded apps, then sign in to Astrill again.No such file or directory (os error 2)Change the model_catalog_json absolute path in config.toml to the relative cc-switch-model-catalog.json, or upgrade cc-switch.Failed to initialize gtk backend cc-switchRunning cc-switch in a headless environment (a server or container) errors for lack of GTK. Use the cc-switch-cli command-line build instead.AbsolutePathBuf deserialized without a basemacOS Codex Desktop users can set model_catalog_json in config.toml to the absolute path of the model catalog file.KMS: DRM_IOCTL_MODE_CREATE_DUMB failed: Permission deniedResolve cc-switch white screen DRM permission errors on Linux by disabling WebKit hardware acceleration, specifying NVIDIA rendering, or using the CLI version.Claude Code shows a white screencc-switch may not start on older systems. On Windows, update to 24H2; on macOS, try the maintainer-recommended CC Switch CLI.http://127.0.0.1:15721 proxy configuration stuckUpgrade to CC Switch v3.16.2 to fix proxy hangs from corrupted backups, or use "Replace Config" mode to manually set env vars.Main Window Never Appears; CC Switch Fails to Start on WindowsCheck Windows updates and WebView2 arguments first; the issues do not confirm a general fix for all cases.Request exceeds the context windowNo verified solution was provided in the original post; this issue was closed as a duplicate related to catalog configuration and automatic compression.Crash on Launch: CC Switch Windows Startup CrashReproduce on the latest version and provide the CC Switch, Windows, and WebView2 versions, along with the latest logs and Event Viewer error details.settings.json Is Fully RewrittenPut retained Claude Code project settings in `.claude/settings.local.json` to avoid loss when cc-switch overwrites user-level `settings.json`.Still includes `disable_response_storage = true`No verified fix is available. A PR proposes removing disable_response_storage from generation paths, but its merge or release is unconfirmed.Cannot Open Codex or Claude Code After DEB Install on deepin23No verifiable solution is available in the original post. Follow the main discussion in #3133 for repair progress.Input field cannot gain focus / cannot enter OpenCodeThere is currently no confirmed fix. In Linux Wayland and NVIDIA environments, the app freezes after entering an edit page.Blank screen when adding a providerUpgrade to CC Switch 4.0.13. If it persists, report it again with the version, system environment, reproduction steps, and logs.invalid function arguments json string: CodexUpgrade cc-switch to 3.16.4 or later, then retest with MiniMax-M3.Cannot open the app after Loading, cc-switch PortableThe original post does not provide a verifiable solution; see the issue's follow-up discussion.Optional isolation forced output Claude CodeSet `strict: false` on ordinary function tools during Responses conversion and preserve the existing required fields in `required`.Claude Code crashes on launchThe original post has not provided a verifiable fix. Follow the subsequent handling in Issue #2923.CC Switch Windows opens to a black screen and crashes after a few secondsWait for a later version that disables Overlay on Windows; the original issue provides no verifiable current fix.Cannot start cc-switch; cc-switch --version produces no outputThe maintainer recommends reinstalling first; if it still cannot start, try the CLI version. Recovery was not confirmed in the original post.
Install and packaging21
macOS cc-switch version detection error / freezeModify the fastfetch call in .zshrc to add a [[ -t 1 ]] check for non-interactive output.cc-switch installation failure: dependency conflict, insufficient permissions, and antivirus false positivesOn older Linux, use a community build for missing dependencies; on Windows, install to AppData if permissions are insufficient;"Failed to upload "image.png"" screenshot upload failedThis is not a cc-switch error. GitHub failed to upload the screenshot. Re-upload it or paste the error as text so maintainers can see it.skills installed to the wrong path - cc-switchOlder cc-switch installs skills into ~/.claude/skills/skills, which Claude Code ignores. Upgrade, or move the contents up to ~/.claude/skills/.Installation reports missing libwebkit2gtk-4.1.so.0 cc-switchOn Rocky 9, the RPM installation fails because a webkit dependency is missing. Upgrade the system to Rocky 10.1 to resolve it.Troubleshooting cc-switch Upgrade Failures, Freezes, and Display CorruptionUpgrade cc-switch: v3.16.3+ fixes update freezes, v3.20.0+ detects winget-installed Claude Code, and v4.0 refactors upgrades. Upgrade winget installs manually.Skill source directory missing SKILL.md; Claude Code skill installation failsIf installation reports missing SKILL.md, check the repository structure and confirm SKILL.md is in the resolved skill directory.`GLIBC_2.35' not foundNo confirmed compatible release exists from v3.10.1–v3.16.1. Try v4; if it still fails, report the version and reproduction steps.openclaw.json is not valid JSON - OpenClawAdd double quotes around the models key in ~/.openclaw/openclaw.json by hand to fix the strict JSON parse failure.Error 2503: CC Switch MSI Installation Fails on Windows 11Open Command Prompt as an administrator and run msiexec /i with the MSI file path.Local Claude CLI installed but Settings says it isn'tUpgrade CC Switch to v3.16.5 or later to fix false installation conflicts and garbled paths on Windows.Symlink target not found: .DirIcon broken symlink causes - CC SwitchAppImage install fails due to broken .DirIcon symlink. Fix by converting it to a relative path.Local proxy toggle UI component is truncated and cannot be fully displayedUpgrade cc-switch to the latest version to fix UI truncation caused by window scaling and tray menu overflow.does not run on macOS versions other than Monterey: CC Switch installation failureRun `brew update` and retry. If the cask is still locked to Monterey, change the macOS condition to `>= :monterey`.error code is 2503: CC Switch installation failureWhen error code 2503 occurs, try the NSIS -setup.exe installer; this issue thread does not confirm that the method works.CC Switch flashes once when clicking any buttonOn Windows, use WebView2 152.0.4191.62 Fixed Version only for CC Switch to avoid click flashing with WebView2 153.0.4234.32.Installation failed: Skill directory does not exist cc-switchUpgrade to cc-switch v3.14.0 or use local ZIP installation to fix URL install failures for repos with SKILL.md in the root.Main Window Never Appears; CC Switch Fails to Start on WindowsCheck Windows updates and WebView2 arguments first; the issues do not confirm a general fix for all cases.1M Context Configuration Not Taking Effect Claude CodeRevert the Opus route in the cc-switch database from claude-opus-4-8 to claude-opus-4-6, then restart Claude Desktop.Cannot Open Codex or Claude Code After DEB Install on deepin23No verifiable solution is available in the original post. Follow the main discussion in #3133 for repair progress.Input should be a valid string: Codex image history 422Most related issues remain unresolved. Upgrade to cc-switch v3.20.4 and retry. If 422 persists, start a new session or roll back before the image.
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.