unslothai/unsloth · error · SttModelCompatibilityError

STT model '{model_id}' is not a compatible Transformers Whis

Error message

STT model '{model_id}' is not a compatible Transformers Whisper model.

What it means

SttModelCompatibilityError raised after a successful model_info() call when the repo's config does not look like a Transformers Whisper model (checked by _is_whisper_config on info.config — e.g. model_type/architectures not matching Whisper). The repo exists and is reachable; it is just the wrong kind of model.

Source

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

    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}


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:

View on GitHub (pinned to 203007d190)

Solutions

Choose a Transformers Whisper repository (config with Whisper model_type/architectures).
Prefer the curated ids in STT_MODELS, which skip verification entirely.
If you maintain the target repo, ensure its config.json carries standard Whisper fields.

Example fix

```python
# before
verify_model("meta-llama/Meta-Llama-3-8B")  # raises: not a Whisper model

# after
verify_model("openai/whisper-large-v3")      # valid Transformers Whisper repo
# or use a curated default:
resolve_model_id(None)  # -> DEFAULT_STT_MODEL
```

Defensive patterns

Strategy: validation

Validate before calling

```python
from huggingface_hub import HfApi
info = HfApi(token=hf_token or False).model_info(repo, expand=["config"])
if not _is_whisper_config(getattr(info, "config", None)):
    reject_model("Not a Transformers Whisper repository")
```

Type guard

```python
def is_whisper_repo(config: object) -> TypeGuard[dict]:
    return _is_whisper_config(config)
```

Try / catch

```python
try:
    meta = verify_model(model_id)
except SttModelCompatibilityError as exc:
    if "not a compatible Transformers Whisper" in str(exc):
        suggest_curated_models()  # user picked the wrong kind of repo
    raise
```

Prevention

Offer curated Whisper models by default.
Show model type in the picker so users see they selected a non-Whisper repo.
Verify once at configuration time, not at every dictation request.

When it happens

Trigger: Pointing the STT backend at a non-Whisper Transformers repo (a text LLM, a vision model) or a Whisper variant whose config lacks the expected Whisper markers.

Common situations: Users pasting a chat-model repo like 'meta-llama/Llama-3-8B' into the voice settings; GGUF-only Whisper mirrors with no Transformers config; Whisper-derived architectures with renamed model_type.

Related errors

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