{"record":{"id":"570b2137903c2cd2","repo":"unslothai/unsloth","slug":"could-not-resolve-an-immutable-revision-for-stt-mo","errorCode":null,"errorMessage":"Could not resolve an immutable revision for STT model '{model_id}'.","messagePattern":"Could not resolve an immutable revision for STT model '(.+?)'\\.","errorType":"http","errorClass":"SttModelCompatibilityError","httpStatus":422,"severity":"error","filePath":"studio/backend/core/inference/stt_sidecar.py","lineNumber":589,"sourceCode":"        from huggingface_hub import HfApi\n        info = HfApi(token = hf_token or False).model_info(\n            repo,\n            expand = [\"config\", \"sha\"],\n            timeout = 10,\n        )\n    except Exception as exc:\n        raise SttModelCompatibilityError(\n            f\"Could not verify STT model '{model_id}'. \"\n            \"Check that the repository exists and your Hugging Face token can access it.\"\n        ) from exc\n\n    if not _is_whisper_config(getattr(info, \"config\", None)):\n        raise SttModelCompatibilityError(\n            f\"STT model '{model_id}' is not a compatible Transformers Whisper model.\"\n        )\n    revision = getattr(info, \"sha\", None)\n    if not isinstance(revision, str) or not _HF_COMMIT_SHA.fullmatch(revision):\n        raise SttModelCompatibilityError(\n            f\"Could not resolve an immutable revision for STT model '{model_id}'.\"\n        )\n    # The commit that was validated; the download pins to it so the repo cannot\n    # be swapped between validation and snapshot_download (TOCTOU).\n    return {\"model\": model_id, \"repo\": repo, \"revision\": revision}\n\n\ndef _is_missing_local_model_error(exc: BaseException) -> bool:\n    \"\"\"Recognize a local-cache-only miss by name/message, without importing HF\n    internals (tolerates huggingface_hub/Transformers moving the exception).\"\"\"\n    current: Optional[BaseException] = exc\n    seen: set[int] = set()\n    while current is not None and id(current) not in seen:\n        seen.add(id(current))\n        if type(current).__name__ in (\"LocalEntryNotFoundError\", \"EntryNotFoundError\"):\n            return True\n        message = str(current).lower()\n        if \"local_files_only\" in message or \"does not appear to have a file\" in message:","sourceCodeStart":571,"sourceCodeEnd":607,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/stt_sidecar.py#L571-L607","documentation":"SttModelCompatibilityError raised when model_info() succeeded and the config is Whisper, but info.sha is missing or does not fullmatch _HF_COMMIT_SHA (a 40-hex commit hash). The revision is required because the download pins to it, preventing the repo from being swapped between verification and snapshot_download (an explicit TOCTOU guard).","triggerScenarios":"A Hub response that omits sha or returns a non-canonical revision (branch name, tag, short hash) — e.g. an Enterprise/mirror Hub deployment, an unexpected huggingface_hub version changing the expand=['sha'] behavior, or a dataset-style endpoint.","commonSituations":"Self-hosted HF mirror not returning commit hashes; huggingface_hub API change dropping the expanded sha field; rare Hub inconsistency during repackaging.","solutions":["Retry verification — transient Hub response anomalies resolve themselves.","Upgrade/downgrade huggingface_hub to a version compatible with the studio backend (via `unsloth studio update`).","If using an HF mirror/proxy, ensure it forwards the commit sha in model_info responses.","Fall back to a curated STT_MODELS id, which needs no revision resolution."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"```python\nimport re\ninfo = HfApi(token=hf_token or False).model_info(repo, expand=[\"sha\"])\nsha = getattr(info, \"sha\", None)\nif not (isinstance(sha, str) and re.fullmatch(r\"[0-9a-f]{40}\", sha)):\n    postpone_or_use_curated_model()  # cannot pin an immutable revision\n```","typeGuard":null,"tryCatchPattern":"```python\ntry:\n    meta = verify_model(model_id)\nexcept SttModelCompatibilityError as exc:\n    if \"immutable revision\" in str(exc):\n        retry_once()  # Hub anomaly; else pin huggingface_hub version\n    raise\n```","preventionTips":["Keep huggingface_hub pinned to the version studio ships (`unsloth studio update`).","Ensure HF mirrors/proxies return full commit SHAs in model_info.","Prefer curated models, which bypass revision resolution entirely."],"tags":["stt","huggingface","revision","toctou","model-verification"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}