unslothai/unsloth · error · SttModelCompatibilityError

Could not resolve an immutable revision for STT model '{mode

Error message

Could not resolve an immutable revision for STT model '{model_id}'.

What it means

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

Source

Thrown at studio/backend/core/inference/stt_sidecar.py:589

        from huggingface_hub import HfApi
        info = HfApi(token = hf_token or False).model_info(
            repo,
            expand = ["config", "sha"],
            timeout = 10,
        )
    except Exception as exc:
        raise SttModelCompatibilityError(
            f"Could not verify STT model '{model_id}'. "
            "Check that the repository exists and your Hugging Face token can access it."
        ) from exc

    if not _is_whisper_config(getattr(info, "config", None)):
        raise SttModelCompatibilityError(
            f"STT model '{model_id}' is not a compatible Transformers Whisper model."
        )
    revision = getattr(info, "sha", None)
    if not isinstance(revision, str) or not _HF_COMMIT_SHA.fullmatch(revision):
        raise SttModelCompatibilityError(
            f"Could not resolve an immutable revision for STT model '{model_id}'."
        )
    # The commit that was validated; the download pins to it so the repo cannot
    # be swapped between validation and snapshot_download (TOCTOU).
    return {"model": model_id, "repo": repo, "revision": revision}


def _is_missing_local_model_error(exc: BaseException) -> bool:
    """Recognize a local-cache-only miss by name/message, without importing HF
    internals (tolerates huggingface_hub/Transformers moving the exception)."""
    current: Optional[BaseException] = exc
    seen: set[int] = set()
    while current is not None and id(current) not in seen:
        seen.add(id(current))
        if type(current).__name__ in ("LocalEntryNotFoundError", "EntryNotFoundError"):
            return True
        message = str(current).lower()
        if "local_files_only" in message or "does not appear to have a file" in message:

View on GitHub (pinned to 203007d190)

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.

Defensive patterns

Strategy: retry

Validate before calling

```python
import re
info = HfApi(token=hf_token or False).model_info(repo, expand=["sha"])
sha = getattr(info, "sha", None)
if not (isinstance(sha, str) and re.fullmatch(r"[0-9a-f]{40}", sha)):
    postpone_or_use_curated_model()  # cannot pin an immutable revision
```

Try / catch

```python
try:
    meta = verify_model(model_id)
except SttModelCompatibilityError as exc:
    if "immutable revision" in str(exc):
        retry_once()  # Hub anomaly; else pin huggingface_hub version
    raise
```

Prevention

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.

When it happens

Trigger: 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.

Common situations: Self-hosted HF mirror not returning commit hashes; huggingface_hub API change dropping the expanded sha field; rare Hub inconsistency during repackaging.

Related errors

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