Skip to content
CC Switch WikiUnofficial Community Wiki

cc-switch import / cloud sync failures: foreign keys, read-only database, overwrites

Quick fix

Upgrade cc-switch and avoid syncing provider_health or a read-only db; after picking a file, click 导入 (Import) rather than 保存 (Save).

Symptom

Section titled “Symptom”
Error output
下载失败：数据库错误: 恢复表 provider_health 数据失败: FOREIGN KEY constraint failed
English translation

Download failed: database error: failed to restore data for table provider_health: FOREIGN KEY constraint failed

Cause

Section titled “Cause”

This cluster covers several kinds of import and sync problem. The most common one: restoring a WebDAV download also syncs the provider_health table, and that table has a foreign key pointing at providers. If one machine deleted a provider while another machine still holds the matching provider_health rows locally, restoring the snapshot trips FOREIGN KEY constraint failed. A maintainer confirmed provider_health should not take part in sync, and fixed it. Other variants: cc-switch.db turns read-only after being synced by a cloud drive, giving attempt to write a readonly database; after importing a config you have to click 导入 (Import) on the left again rather than only 保存 (Save); syncing an old-style config directory lets the last active provider overwrite other machines; and audit-level problems in 3.19.1 where the profiles table did not trigger WebDAV/S3 auto-sync and SQL backup/restore could lose the AUTOINCREMENT high-water mark.

Fix

Section titled “Fix”

  1. Upgrade cc-switch on both ends to a version that includes the fix. A maintainer confirmed the provider_health-in-sync problem is fixed and ships with newer releases.

  2. If you sync over WebDAV or a cloud drive, sync only cc-switch.db, not the whole old config directory. Newer versions use a layered storage architecture and only the database file needs syncing.

  3. If you get attempt to write a readonly database, check the permissions on cc-switch.db in the sync directory, make it read-write, and restart cc-switch.

    cc-switch.db（位于你设置的云同步文件夹内）
    # 将文件权限从只读改为读写

  4. When importing JSON or a backup by hand, pick the file and then click the 导入 (Import) button on the left, not just 保存 (Save) below. Users have confirmed the import succeeds that way.

  5. If the cloud copy has already been upgraded to db-v6 and the old data will not restore, install the older cc-switch first to sync the data back, then upgrade again.

  6. On a WebDAV 401, check the server path, credentials, and permissions. Some users mention having to disable the 1024 path check.

Affected Versions

Section titled “Affected Versions”
Toolcc-switch
VersionUnknown
PlatformsWindowsmacOSLinux

Source Issues

Section titled “Source Issues”

This page is distilled from 25 real issues

FAQ

Section titled “FAQ”
Both machines are on the latest version — why does the WebDAV download still report FOREIGN KEY constraint failed?
Because one machine deleted a provider while the other still holds the matching provider_health rows locally. Restoring the cloud snapshot finds no matching providers row and the foreign key fails. A maintainer has confirmed provider_health should not take part in sync.
I imported a config file and nothing changed. Why?
After picking the file you have to click the 导入 (Import) button on the left again, not just 保存 (Save) below. Users have confirmed that works.
Why do I get attempt to write a readonly database after syncing with a cloud drive?
cc-switch.db in the sync folder may have turned read-only. Find that database file, make it read-write, and restart cc-switch.
Can I still restore the old data after the cloud copy became db-v6?
Yes. Install the older cc-switch first, sync the cloud data back, then upgrade to the new version.
WebDAV returns 401. What now?
Check the WebDAV account, password, path, and permissions. Some users mention that certain servers need the 1024 path check disabled.
Does MCP configuration sync automatically?
In the early design, MCP data was imported once on first run only when the app had none. MCP installed later by other means does not sync automatically. A maintainer mentioned a manual sync button is planned for a future version.
Section titled “Related problems”
Error in .codex cc-switch.db causes cc-switch startup failureClose cc-switch, clean records with empty base_url in cc-switch.db, or delete the database file and restart.1 issues mergedcc-switch Skills management problems (duplicates, not detected, deleted repos returning, inconsistent state)Most Skills problems are fixed in later versions: v3.18.0 stops deleted default repos returning; v3.13.0 improves installed-Skill detection and dedup.18 issues mergedEvery 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.3 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.