unslothai/unsloth · error · HTTPException

Could not verify {model!r} as an embedding model on Hugging

Error message

Could not verify {model!r} as an embedding model on Hugging Face (it may be the wrong model type, gated, or you may be offline).

What it means

HTTP 409 from the embedding-model endpoint when the requested model differs from the default, force is not set, and is_embedding_model() cannot verify it as a sentence-transformers layout — and (offline case) the local cache is not a genuinely loadable snapshot (config + weights via hf_cache_snapshot_is_loadable). This 409 is forceable: sending force:true skips the verification gate.

Source

Thrown at studio/backend/routes/settings.py:1645

        from core.rag import config as rag_config

        # A GGUF-named repo on the llama-server backend is loaded from its .gguf
        # files, which rarely carry sentence-transformers metadata; verify the
        # GGUF is available (below) rather than the ST embedding-metadata gate,
        # which would wrongly 409 a valid online GGUF embedder.
        gguf_named = _llama_backend_active() and rag_config._names_gguf(model)
        if not gguf_named and not is_embedding_model(model, hf_token = hf_token):
            # Offline, is_embedding_model can only confirm the ST layout (modules.json); a
            # transformers-native embedder (e.g. gte-modernbert) is unverifiable without Hub
            # metadata. If already cached and loadable, accept it rather than raising a 409 that
            # online would not (ST can load any cached encoder). Uncached -> 409.
            from utils.utils import hf_cache_snapshot_is_loadable

            # Require a genuinely loadable cache (config + weights), not just a resolved refs/main,
            # so a metadata-only partial cache still gets the forceable 409.
            offline_cached = local_only_load and hf_cache_snapshot_is_loadable(model)
            if not offline_cached:
                raise HTTPException(
                    status_code = 409,
                    detail = (
                        f"Could not verify {model!r} as an embedding model on "
                        "Hugging Face (it may be the wrong model type, gated, or "
                        "you may be offline)."
                    ),
                )
        # The Hub GGUF probe (list_repo_files) can hang offline; skip it. Local check stays.
        gguf_error = _local_gguf_backend_error(model)
        if gguf_error is None and not local_only_load:
            gguf_error = _hf_gguf_backend_error(model, hf_token)
        if gguf_error:
            raise HTTPException(status_code = 409, detail = gguf_error)
    set_rag_embedding_model(model)
    logger.info(
        "settings.embedding_model_updated subject=%s model=%s forced=%s",
        current_subject,
        model,

View on GitHub (pinned to 203007d190)

Solutions

1. Check spelling/org of the model id and that it is actually a sentence-transformers embedding model on the Hub.
2. If gated: accept the license on Hugging Face and set a valid token via the token endpoint, then retry.
3. If offline: finish the download (cache must include config + weights), then retry — or go online.
4. If you know the model is valid (e.g. transformers-native embedder already cached and loadable), resend with force:true to skip verification.

Example fix

# before
PUT /settings/embedding-model {"model": "BAAI/bge-m3 "}  # 409, typo/offline

# after
PUT /settings/embedding-model {"model": "BAAI/bge-m3"}            # fixed id, online
# or, trusted non-ST embedder already cached:
PUT /settings/embedding-model {"model": "Alibaba-NLP/gte-modernbert-base", "force": true}

const verified = await api.canVerifyEmbeddingModel(model); // or Hub API metadata check
if (!verified) {
  await api.put('/settings/embedding-model', { model, force: true }); // only when you trust the model
} else {
  await api.put('/settings/embedding-model', { model });
}

function needsForce(opts: { offline: boolean; cacheLoadable: boolean; stLayout: boolean }): boolean {
  return !opts.stLayout && !(opts.offline && opts.cacheLoadable);
}

try { await api.put('/settings/embedding-model', { model }); }
catch (e) {
  if (e.status === 409 && /Could not verify/.test(e.detail)) {
    // wrong type / gated / offline — fix the root cause, or force if trusted:
    return api.put('/settings/embedding-model', { model, force: true });
  }
  throw e;
}

When it happens

Trigger: PUT embedding-model with a wrong-type repo (a generation or classification model), a gated repo your token cannot read, a typo'd model id, or any model while offline whose cache is only metadata/partial. The GGUF-named exception applies only when the llama-server backend is active and the name resolves to GGUF.

Common situations: Users entering 'BAAI/bge-m3' variants with wrong casing or org; gated models needing HF token acceptance; offline setups with interrupted downloads (refs resolved but no weights); transformers-native embedders like gte-modernbert that lack modules.json.

Related errors

• gguf_error
• {model!r} has cached pickle weights that cannot be security-
• str(exc)
• fill_absent_fields cannot be combined with remove.
• {model!r} is flagged as unsafe by Hugging Face's security sc

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