unslothai/unsloth · error · SttModelCompatibilityError

Could not verify STT model '{model_id}'. Check that the repo

Error message

Could not verify STT model '{model_id}'. Check that the repository exists and your Hugging Face token can access it.

What it means

SttModelCompatibilityError raised when the HfApi.model_info() call for a custom (non-curated) model id fails for any reason — network error, unknown repository, private repo without/with a bad token, or the 10s timeout elapsing. The original exception is chained via `from exc` for diagnosis.

Source

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

    return tuple(_selected_file_from_sibling(siblings[name]) for name in sorted(selected))


def validate_remote_model(model: Optional[str], hf_token: Optional[str] = None) -> dict:
    """Verify a custom Hub repository is Whisper-compatible without downloading weights."""
    model_id = resolve_model_id(model)
    repo = resolve_model_repo(model_id)
    if model_id in STT_MODELS:
        return {"model": model_id, "repo": repo}

    try:
        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}

View on GitHub (pinned to 203007d190)

Solutions

Check the repository exists at huggingface.co/{owner}/{model} and the id is spelled exactly.
For private/gated repos, supply a valid Hugging Face token with read access.
Check connectivity to huggingface.co (proxy/firewall) and retry.
Inspect the chained exception (`raise ... from exc`) to see whether it was auth, DNS, or timeout.

Defensive patterns

Strategy: retry

Validate before calling

```python
import requests
requests.head(f"https://huggingface.co/{repo}", timeout=5, allow_redirects=True)  # 200/401/403 => repo exists
```

Try / catch

```python
try:
    meta = verify_model(model_id, hf_token=token)
except SttModelCompatibilityError as exc:
    if "Could not verify" in str(exc):
        check_network_and_token(exc.__cause__); retry_with_backoff()
    raise
```

Prevention

Prompt for a Hugging Face token before users add private/gated models.
Distinguish auth vs network from the chained exception before retrying.
Cache verification results so flaky networks do not re-hit the Hub per request.

When it happens

Trigger: Verifying a custom 'owner/model' id whose repo does not exist, is private and hf_token is None/invalid, the machine is offline, or huggingface_hub raising any exception during model_info(expand=['config','sha']).

Common situations: Typo'd owner or model name; gated/private Whisper repos needing a PAT the user never entered; corporate proxy blocking huggingface.co; flaky network during Settings > Voice model verification.

Related errors

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