{"record":{"id":"cdba44bcace91634","repo":"unslothai/unsloth","slug":"backend-switch-must-preserve-repo-pin-release-t","errorCode":null,"errorMessage":"backend switch must preserve {repo}@{pin_release_tag}, but installer produced {new_repo or 'an unknown repository'}@{new_tag or 'an unknown release'}","messagePattern":"backend switch must preserve (.+?)@(.+?), but installer produced (.+?)@(.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"studio/backend/utils/llama_cpp_update.py","lineNumber":672,"sourceCode":"\n        # Drop stale caches so the banner re-checks the swapped marker.\n        # If GitHub is offline, latest stays unknown and the banner fails open.\n        reset_caches(drop_disk = True)\n        # The cached options describe the previous install.\n        _backends_memo.clear()\n        try:\n            latest_published_release(repo, force_refresh = True)\n        except Exception as exc:  # pragma: no cover - network defensive\n            logger.debug(\"llama update: post-install freshness refresh failed\", error = str(exc))\n        new_marker = read_install_marker(_find_binary())\n        new_tag = (new_marker or {}).get(\"release_tag\") or (new_marker or {}).get(\"tag\")\n        new_backend = marker_backend(new_marker)\n        new_backend_request = marker_backend_request(new_marker)\n\n        new_repo = (new_marker or {}).get(\"published_repo\")\n        if pin_release_tag and backend_request is not None:\n            if new_repo != repo or new_tag != pin_release_tag:\n                raise RuntimeError(\n                    \"backend switch must preserve \"\n                    f\"{repo}@{pin_release_tag}, but installer produced \"\n                    f\"{new_repo or 'an unknown repository'}@{new_tag or 'an unknown release'}\"\n                )\n        elif pin_release_tag and new_tag and new_repo == repo and new_tag != pin_release_tag:\n            raise RuntimeError(f\"pinned release {pin_release_tag} but installer produced {new_tag}\")\n\n        if backend_request is not None:\n            if new_backend is None:\n                raise RuntimeError(\n                    f\"requested {backend_request} but the installed backend is unknown\"\n                )\n            if new_backend_request != backend_request:\n                raise RuntimeError(\n                    f\"requested {backend_request} but the installer recorded \"\n                    f\"{new_backend_request or 'an unknown selection'}\"\n                )\n            if backend_request != \"auto\" and new_backend != backend_request:","sourceCodeStart":654,"sourceCodeEnd":690,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/utils/llama_cpp_update.py#L654-L690","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Re-run the switch; a transient marker race is the most common cause","Verify the pinned tag still exists in the expected repo (GitHub releases page or latest_published_release(repo))","If the repo moved/renamed, update the repo argument to the new canonical name and retry","If it persists, delete the managed runtime/marker so the next run does a clean install, then re-pin"],"exampleFix":"# before\nswitch_result = run_update(backend_request='vulkan', pin_release_tag='b1234')\n# RuntimeError: backend switch must preserve ggml-org/llama.cpp@b1234,\n#               but installer produced ggml-org/llama.cpp@b5678\n\n# after: pin the tag the installer can actually deliver, or clear the pin\nswitch_result = run_update(backend_request='vulkan', pin_release_tag='b5678')","handlingStrategy":"try-catch","validationCode":"from utils.llama_cpp_update import read_install_marker, _find_binary\n\ndef pin_will_hold(repo: str, tag: str) -> bool:\n    m = read_install_marker(_find_binary()) or {}\n    return m.get('published_repo') == repo and (m.get('release_tag') or m.get('tag')) == tag","typeGuard":null,"tryCatchPattern":"try:\n    run_update(backend_request=sel, pin_release_tag=tag)\nexcept RuntimeError as exc:\n    if 'backend switch must preserve' in str(exc):\n        reconcile_pin_with_latest_release()  # pin drifted; re-pin to what exists\n    else:\n        raise","preventionTips":["Pin only tags confirmed to exist via latest_published_release(repo)","Avoid concurrent backend switches on one runtime","Treat these RuntimeErrors as invariant failures: retry once, then investigate the marker"],"tags":["llama-cpp","runtime-installer","backend-switch","release-pin","invariant"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}