unslothai/unsloth · error · RuntimeError

backend switch must preserve {repo}@{pin_release_tag}, but i

Error message

backend switch must preserve {repo}@{pin_release_tag}, but installer produced {new_repo or 'an unknown repository'}@{new_tag or 'an unknown release'}

What it means

Post-install invariant check in the llama.cpp backend-switch flow: when the caller pinned a release tag AND supplied a backend_request, the freshly read install marker must still report the same repo and tag. A backend switch (e.g. CUDA to Vulkan) reinstalls a binary, and this guard proves the reinstall did not drift to a different repository (ggml-org vs a fork) or a different release than the one pinned.

Source

Thrown at studio/backend/utils/llama_cpp_update.py:672

        # Drop stale caches so the banner re-checks the swapped marker.
        # If GitHub is offline, latest stays unknown and the banner fails open.
        reset_caches(drop_disk = True)
        # The cached options describe the previous install.
        _backends_memo.clear()
        try:
            latest_published_release(repo, force_refresh = True)
        except Exception as exc:  # pragma: no cover - network defensive
            logger.debug("llama update: post-install freshness refresh failed", error = str(exc))
        new_marker = read_install_marker(_find_binary())
        new_tag = (new_marker or {}).get("release_tag") or (new_marker or {}).get("tag")
        new_backend = marker_backend(new_marker)
        new_backend_request = marker_backend_request(new_marker)

        new_repo = (new_marker or {}).get("published_repo")
        if pin_release_tag and backend_request is not None:
            if new_repo != repo or new_tag != pin_release_tag:
                raise RuntimeError(
                    "backend switch must preserve "
                    f"{repo}@{pin_release_tag}, but installer produced "
                    f"{new_repo or 'an unknown repository'}@{new_tag or 'an unknown release'}"
                )
        elif pin_release_tag and new_tag and new_repo == repo and new_tag != pin_release_tag:
            raise RuntimeError(f"pinned release {pin_release_tag} but installer produced {new_tag}")

        if backend_request is not None:
            if new_backend is None:
                raise RuntimeError(
                    f"requested {backend_request} but the installed backend is unknown"
                )
            if new_backend_request != backend_request:
                raise RuntimeError(
                    f"requested {backend_request} but the installer recorded "
                    f"{new_backend_request or 'an unknown selection'}"
                )
            if backend_request != "auto" and new_backend != backend_request:

View on GitHub (pinned to 203007d190)

Solutions

  1. Re-run the switch; a transient marker race is the most common cause
  2. Verify the pinned tag still exists in the expected repo (GitHub releases page or latest_published_release(repo))
  3. If the repo moved/renamed, update the repo argument to the new canonical name and retry
  4. If it persists, delete the managed runtime/marker so the next run does a clean install, then re-pin

Example fix

# before
switch_result = run_update(backend_request='vulkan', pin_release_tag='b1234')
# RuntimeError: backend switch must preserve ggml-org/llama.cpp@b1234,
#               but installer produced ggml-org/llama.cpp@b5678

# after: pin the tag the installer can actually deliver, or clear the pin
switch_result = run_update(backend_request='vulkan', pin_release_tag='b5678')
Defensive patterns

Strategy: try-catch

Validate before calling

from utils.llama_cpp_update import read_install_marker, _find_binary

def pin_will_hold(repo: str, tag: str) -> bool:
    m = read_install_marker(_find_binary()) or {}
    return m.get('published_repo') == repo and (m.get('release_tag') or m.get('tag')) == tag

Try / catch

try:
    run_update(backend_request=sel, pin_release_tag=tag)
except RuntimeError as exc:
    if 'backend switch must preserve' in str(exc):
        reconcile_pin_with_latest_release()  # pin drifted; re-pin to what exists
    else:
        raise

Prevention

When it happens

Trigger: Calling the update/switch routine with pin_release_tag set and backend_request not None, then read_install_marker(_find_binary()) returns a marker whose published_repo differs from repo, or whose release_tag/tag differs from pin_release_tag — e.g. the pinned tag was yanked and the installer fell back to latest, the repo redirect moved, or the marker belongs to a stale/corrupt install.

Common situations: Switching GPU backend (CUDA<->Vulkan/Metal) while a specific release is pinned; upstream repo renames breaking published_repo equality; partially failed installs leaving a marker from the previous binary; concurrent update runs clobbering the marker.

Related errors

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/cdba44bcace91634. Report an issue: GitHub.