Skip to content
CC Switch WikiUnofficial Community Wiki

Error in .codex cc-switch.db causes cc-switch startup failure - cc-switch

Quick fix

Close cc-switch, clean records with empty base_url in cc-switch.db, or delete the database file and restart.

Symptom

Section titled “Symptom”
Error output
报.codex下的cc-switch.db出错，然后启动cc-switch失败。
English translation

An error is reported in .codex cc-switch.db, and then cc-switch fails to start.

Cause

Section titled “Cause”

When editing or deleting Provider configurations, state synchronization failures can leave invalid Provider records with empty key fields such as base_url in cc-switch.db. At startup, the proxy reads the invalid record, overrides valid configuration, and throws a configuration error. Because the frontend UI has already removed the record, users cannot fix it through the interface.

Fix

Section titled “Fix”

  1. Fully close the CC Switch application and its background processes.

  2. Locate the database file ~/.cc-switch/cc-switch.db (on Windows: C:\Users\<用户名>\.cc-switch\cc-switch.db; in some environments it may be ~/.codex/cc-switch.db).

  3. Open it with an SQLite tool and delete abnormal records with empty base_url, or delete the entire cc-switch.db file.

  4. Reopen CC Switch and reconfigure the Provider.

Affected Versions

Section titled “Affected Versions”
Toolcc-switch
VersionUnknown
PlatformsWindowsmacOSLinux

Source Issues

Section titled “Source Issues”

This page is distilled from 1 real issues

FAQ

Section titled “FAQ”
What if deleting ~/.codex/cc-switch.db still results in a startup failure?
Also check and clean the Windows host configuration directory, such as C:\Users\<用户名>\.cc-switch\cc-switch.db, and fully stop all cc-switch processes before deleting.
Why is the residual record causing the error not visible in the UI?
The frontend state removed it during the delete operation, but the underlying database was not cleaned up correctly, leaving the UI and database state inconsistent.
Section titled “Related problems”
cc-switch config not applied / not picked up after switching - Claude CodeConfirm the app actually reads the config path cc-switch writes to, then check routing and plugin toggles, duplicate keys, and version compatibility.28 issues mergedcc-switch DeepSeek usage statistics inaccurate / balance query failsUpgrade to v3.19.2 and rebuild Codex usage. The balance query needs a correct {{apiKey}}, or a proxy.17 issues mergedClaude Official check failed: could not extract base_url - CodexCC Switch proxying and load balancing do not support an official Claude subscription — use a third-party API key. Forcing it errors and risks a ban.4 issues merged

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.