Skip to content
CC Switch WikiUnofficial Community Wiki

protocol handler not registered - cc-switch

Quick fix

On 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.

Symptom

Section titled “Symptom”
Error output
CC-Switch not installed or protocol handler not registered.

Cause

Section titled “Cause”

Import and sync fail through different mechanisms in different environments. On Linux, Chromium-based browsers (Edge, Chrome) require the Exec line of a desktop shortcut to include %U or %u before treating it as a valid URL protocol handler. The cc-switch .deb package omits that argument by default, so the browser blocks an import link called from a web page.

Separately, in a mixed Windows and WSL environment, cross-system sync (a skill symlink, for instance) fails to create the symlink because of permissions or filesystem differences, and reading config and MCP under a WSL directory also has path mapping problems.

Fix

Section titled “Fix”

  1. On Linux, edit the cc-switch desktop shortcut file by hand and add the %U argument to Exec.

    /usr/share/applications/CC Switch.desktop
    Exec=cc-switch
    Exec=cc-switch %U

  2. Or fix it in one command in a Linux terminal (note a software update may overwrite it, so you may need to run it again): sudo sed -i 's/^Exec=cc-switch$/Exec=cc-switch %U/' "/usr/share/applications/CC Switch.desktop"

  3. If creating a symlink fails syncing a skill to WSL from Windows, make sure Windows developer mode is on and run cc-switch as administrator.

Affected Versions

Section titled “Affected Versions”
Toolcc-switch
Version3.16.1 - 3.16.4
PlatformsLinuxWindows

Source Issues

Section titled “Source Issues”

This page is distilled from 3 real issues

FAQ

Section titled “FAQ”
Why does xdg-open work while Chrome/Edge does not?
Chromium browsers have an extra validation step requiring the desktop file Exec line to contain %U or %u; xdg-open has no such restriction.
Syncing a skill to WSL from Windows reports "failed to create symlink". What now?
Confirm Windows developer mode is on and run cc-switch as administrator. If it still fails, it may be a cross-filesystem symlink limitation, which the current version supports only partially.
Section titled “Related problems”
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.3 issues mergedAtomic 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.1 issues mergedA 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.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.