Install and launch problems
Won’t install, won’t open, broken after an update — all of it is here.
129 topic pages, distilled from 618 real issuesHow this is counted
Terminal and environment variables78
cc-switch local proxy: 502 Bad Gateway, timeouts, cannot delete a providerUsually caused by unsupported official providers, config not applying, or UI state drift. Check proxy mode, provider type, and takeover state.Codex usage statistics doubled or inflatedUpgrade to v3.19.2 and run "Rebuild Codex Usage" on the usage page to correct historical inflated data.'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.cc-switch white screen / black screen / crash / no window on launchWork out whether it is corrupt window state, a WebView2/OS compatibility problem, or security software. Handle per symptom; use the CLI build if needed.cc-switch loses Claude Code / Codex MCP configurationUpgrade cc-switch, disable or use unified MCP takeover carefully, find the one broken MCP entry, and fix rewritten command/type/path fields.content[].thinking must be passed backUpgrade cc-switch to v3.16.0 or newer. As a stopgap, roll Claude Code back to 2.1.150 or turn thinking off.ANTHROPIC_BASE_URL rewritten to 127.0.0.1With local routing on, ANTHROPIC_BASE_URL pointing at http://127.0.0.1:15721 is expected. Move shared fields into 通用配置 and restart Claude Code.claude mcp list shows ✘ Failed to connectOn Windows cc-switch wraps the MCP npx command in cmd /c, breaking the stdio pipe. Edit ~/.claude.json back by hand, or rewrite with claude mcp add.settings.json Full Overwrite Causes Plugin FailureUpgrade to v3.20.1+ to fix the bug that clears enabledPlugins when switching configs.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.unexpected status 502 Bad Gateway CodexSet 127.0.0.1 to direct in your proxy software, or configure NO_PROXY in the Codex environment, so the local proxy is not intercepted.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.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.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.Auth conflictDelete primaryApiKey from claude.json, or change the environment variable to ANTHROPIC_API_KEY, to resolve the auth conflict.bash: cannot set terminal process group - cc-switchA known 3.18.0 bug when checking the local proxy environment on Linux. Downgrade below 3.18.0 and configure the proxy in the terminal by hand.env: node: No such file or directoryUpgrade cc-switch to v3.18.0+, which fixes node not being found when updating Codex because a macOS GUI launch has no PATH.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.Your access token could not be refreshedUpgrade cc-switch to v3.17.0+, which fixes the PROXY_MANAGED placeholder polluting OAuth credentials or causing a 401 during takeover.I selected proxy forwarding to a remote host but it still forwards locally - CC SwitchDelete the .cc-switch config directory to clear the cache, and upgrade to v3.17.0 for the relay restriction and statistics fixes.temporarily unavailable, so auto mode cannotUpgrade cc-switch to v3.15.0+ for the model mapping and thinking conversion fixes, or override the default model env var in general config.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+.'claude' is not recognized as an internal or external commandManually specify the full path to the claude executable in CC Switch settings, or ensure the path is added to the system PATH.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.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.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.Several installations detected, or shown as not installed - Codex/OpenCodeUpgrade CC Switch to v3.17.0 or newer, fixing npm path resolution on Windows and the wrapper script misdetection.Every click first pops up the system folder picker - cc-switchEdit src/App.tsx to remove the pickDirectory() call in handleOpenTerminal, so opening a terminal stops forcing a folder picker.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.401 authentication failed: Claude Desktop gateway token invalidClear the official Claude Desktop OAuth login state, or edit .claude.json, to resolve the 401 invalid gateway token.auth.json not updated after switching channel - CodexCodex auth.json is not updated after switching channels. Manually modify auth.json or wait for cc-switch to fix it.A disabled MCP becomes active again after restarting the machine - CodexNo official fix yet: clean the conflicting MCP nodes out of the config file by hand, and use deeplink import carefully so custom settings survive.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.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.cc-switch keeps deleting my environment variablesClosing the conflict dialog does not delete anything. To clear it for good, remove the entry from your shell config or the Hermes config.yaml.Error running remote compact task - CodexUpgrade cc-switch to v3.12.0 or newer, which added forwarding for the Codex `/responses/compact` route in the local proxy, fixing the 404 or 502.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.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.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.InputValidationError: Write failedTurn Tool Search, maximum-effort thinking, and the 1M context declaration off in cc-switch to reduce long-text truncation, or roll back to 3.13.0.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.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 install permission deniedRun msiexec from an administrator command prompt, or download the Portable build, to work around the Windows 11 MSI permission restriction.claude cli exists locally but the about settings say not installed - CC SwitchUpgrade CC Switch to v3.16.5 or newer, fixing the false conflict from multiple npm global package entry points on Windows and the garbled paths.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.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.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.Connecting gpt5.5 in the codex desktop client, image input and reasoning strength switching do not work - CodexDelete the cc-switch config file under Codex and let it rebuild, or edit cc-switch-model-catalog.json to add the missing reasoning tiers and image modality.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.Model mapping does not apply when connecting a Copilot subscriptionUpgrade to v3.15.0 or newer to fix the Copilot subscription model mapping not applying."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_signatureTriggering a tool call with Gemini Native in Claude Desktop proxy mode loses the thought_signature to a session ID mismatch. Await the official fix.version `GLIBC_2.35' not foundThe official AppImage needs a newer GLIBC. On RHEL/Rocky Linux, use the community Flatpak build or one built on an older base image.Model always thinks; disable not supported; use low, high, or maxSet glm-5.3 to forced thinking in cc-switch config; disable thinking.type: disabled.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.This software does not run on macOSRun `brew update` and retry the install, or download the DMG from GitHub Releases and install it by hand.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.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.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.thinking enabled but reasoning_content missingDisable Thinking mode in Claude Code, or upgrade cc-switch to fix Kimi/Moonshot tool call errors.'/d' is not recognized as an internal or external command CC SwitchBypass '/d' errors by using English directories or mklink /J junctions; fix permanently by ensuring .bat files use CRLF and chcp 65001.claude.ai connectors are disabledUnset `ANTHROPIC_API_KEY` to restore claude.ai login and organization connector loading.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.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 cannot be applied in VS CodeRemove old Claude Code proxy settings in VS Code, then toggle Apply to Claude Code plugin in cc-switch again.Atomic replace failed os error 50Change the Claude Code configuration directory from a WSL path back to a Windows local path, or roll back to v3.19.0.Body text appears in thinking blocks, visible text nearly emptyUpgrade cc-switch to a build with PR #4210. Reactive thinking-placeholder handling fixes long-context freezes and body-text collapse.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.Installed but cannot run in current environment, please check CC SwitchUpgrade to CC Switch v3.16.1+ to fix Windows `cmd /C` quote handling that misreports installed CLI as broken.
Update and upgrade36
Codex API key automatically modified leading to model xxx not foundUpgrade to v3.19.2+ to fix incorrect API Key convergence caused by reading auth.json when multiple suppliers share the same address.Claude Code errors or model mapping fails with the CC Switch proxy onUpgrade to v3.15.0 or newer, then set the global outbound proxy explicitly in cc-switch so a stale system proxy cannot be cached by an old process.Failed to fetch the model listUpgrade cc-switch and add a model row before fetching the list. If it still fails, verify /v1/models permissions with curl.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.<!-- Failed to upload "image.png" -->Screenshot upload failures do not affect the issue itself; please describe the error message in text.Cannot 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.unexpected status 502 Bad Gateway CodexSet 127.0.0.1 to direct in your proxy software, or configure NO_PROXY in the Codex environment, so the local proxy is not intercepted.Auto-upgrade fails; reinstalling the new version still leaves the old oneUninstall the old version completely, clear the leftovers, and reinstall — that resolves a failed auto-upgrade or a version that will not update.auth.json under .claude is forcibly replaced after a restart - CodexUpgrade cc-switch to the latest version, or turn proxy takeover off before signing in officially, so a stale snapshot cannot overwrite official credentials.bash: cannot set terminal process group - cc-switchA known 3.18.0 bug when checking the local proxy environment on Linux. Downgrade below 3.18.0 and configure the proxy in the terminal by hand.Is codex no longer supported now that it became ChatGPT? - cc-switchUpgrade to cc-switch v3.17.0, which supports provider switching after Codex merged into ChatGPT Desktop, so old config is not overwritten.codex session expired - CodexBack up the config, then sync the auth.json token into the cc-switch database with a script, or turn usage refresh off so old data cannot overwrite it.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.No providers have been added yet - CC SwitchAfter an upgrade or cloud sync the UI state and the database fall out of sync. Restart the app fully, or re-import a backup, to get the provider list back.The Codex Desktop UI project list is completely empty - CodexCC Switch changed the model_provider key name. Set it back to custom, or upgrade. Lost official login and fewer reasoning tiers remain unresolved.Switching with cc-switch has no effect - CodexCodex does not hot-switch. Restart the Codex app completely after switching relay in cc-switch; a migration tool can recover lost sessions.Failed to fetch models - cc-switchUpgrade cc-switch to v3.16.4+ for the 404 probe fix. On a Coding Plan, change the API address by hand and enter the model names yourself.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 must be a same-origin request - cc-switchSwitch to the generic or custom template in cc-switch and put the usage query URL straight into the request address, bypassing the same-origin restriction."is not a model this version of Claude Code recognizes" - CC SwitchSet CLAUDE_CODE_MAX_CONTEXT_TOKENS or append [1m] to the model name to define the correct context window size.Frozen after clicking updateForce quit and reopen the app, or update by hand to v3.16.3 or newer for the update deadlock fix.os error 183, cannot create a file when that file already exists - Claude CodeOn Windows, cc-switch reports os error 183 when the config directory is a Junction. Remove the directory link for now, or wait for an official 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.macOS cc-switch version detection error / freezeModify the fastfetch call in .zshrc to add a [[ -t 1 ]] check for non-interactive output.codex cli failed - CC SwitchUpgrading cc-switch to v3.16.3 or newer fixes the local environment detection and the blocked upgrade path.[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.This model is not supported when usingComment out model_provider = custom in config.yaml to go back to the official OpenAI provider.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.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 or icon turns white after upgradeRemove Icon="ProductIcon" from per-user-main.wxs to fix install errors and missing icons. Existing users must unpin and repin.Configuration UI FlickeringUpgrade cc-switch to fix flickering from async form loading; read SQLite DB to fix env vars not updating with providers.unexpected status 403 ForbiddenDisable 'Keep Official Login' in CC Switch and restart to stop Codex from sending image gen requests causing 403 errors.unexpected status 403 ForbiddenDisable the cc-switch local proxy or check upstream API access to the codex-auto-review model.
Launch crash / blank screen16
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.cc-switch white screen / black screen / crash / no window on launchWork out whether it is corrupt window state, a WebView2/OS compatibility problem, or security software. Handle per symptom; use the CLI build if needed.EGL_BAD_PARAMETER white screen error - cc-switchInstall the native .deb or AUR package instead, or run the AppImage with LD_PRELOAD pointing at the system library, to resolve the ABI conflict.Missing supports_reasoning_summaries field - CodexUpgrade cc-switch to v3.18.0 or newer, which fixes required fields missing from the generated model catalogue and stopping Codex from starting.assertion failedUpgrade cc-switch to the latest version for the underlying GUI framework crash fix, or try closing proxy software and resetting the network.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.HTTP 400 unknown model 'ark-code-latest'Change the MiniMax provider model ID in CC Switch from the Volcengine-only ark-code-latest to MiniMax-M3 to resolve this 400.The interface does not refresh by itself; only dragging the window triggers a UI redrawUpgrade to v3.13.0+ for the Linux interface freeze fix; the Windows built-in Administrator needs a registry change to open the main window.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 base pathOn Codex for macOS, relative paths written by cc-switch cause this error. Change `model_catalog_json` in `~/.codex/config.toml` to an absolute path.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.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 completely blank (pure white)Set WEBKIT_DISABLE_DMABUF_RENDERER=0 to restore normal rendering under WebKitGTK 2.52 + Mesa."event handler is re-entrant" error or startup crashUninstall Windows update KB5081263 or wait for cc-switch upgrade to avoid crashes and UI rendering failures caused by TAO EventLoop re-entry.cc-switch crashes immediately after openingNo confirmed fix. Reinstalling does not help. Collect debug logs and wait for an official fix.
Install and packaging15
<!-- Failed to upload "image.png" -->Screenshot upload failures do not affect the issue itself; please describe the error message in text.Install reports libwebkit2gtk-4.1.so.0 is missing - cc-switchInstalling the rpm on Rocky 9 fails on a missing webkit dependency. Upgrading the system to Rocky 10.1 resolves 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/.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.The Skill source directory has no SKILL.md; refusing to sync to avoid overwriting the target directoryCC Switch fails to install when the skill repository layout does not match the skillId or is nested — install by hand with `npx skills add`.Error 2503 - cc-switch MSI install permission deniedRun msiexec from an administrator command prompt, or download the Portable build, to work around the Windows 11 MSI permission restriction.claude cli exists locally but the about settings say not installed - CC SwitchUpgrade CC Switch to v3.16.5 or newer, fixing the false conflict from multiple npm global package entry points on Windows and the garbled paths.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.Cannot 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.version `GLIBC_2.35' not foundThe official AppImage needs a newer GLIBC. On RHEL/Rocky Linux, use the community Flatpak build or one built on an older base image.This software does not run on macOSRun `brew update` and retry the install, or download the DMG from GitHub Releases and install it by hand.error code is 2503 or icon turns white after upgradeRemove Icon="ProductIcon" from per-user-main.wxs to fix install errors and missing icons. Existing users must unpin and repin.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."event handler is re-entrant" error or startup crashUninstall Windows update KB5081263 or wait for cc-switch upgrade to avoid crashes and UI rendering failures caused by TAO EventLoop re-entry.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.
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.