{"record":{"id":"08ac89425d1398ff","repo":"unslothai/unsloth","slug":"could-not-verify-model-r-as-an-embedding-model-o","errorCode":null,"errorMessage":"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).","messagePattern":"Could not verify (.+?) as an embedding model on Hugging Face \\(it may be the wrong model type, gated, or you may be offline\\)\\.","errorType":"http","errorClass":"HTTPException","httpStatus":409,"severity":"error","filePath":"studio/backend/routes/settings.py","lineNumber":1645,"sourceCode":"        from core.rag import config as rag_config\n\n        # A GGUF-named repo on the llama-server backend is loaded from its .gguf\n        # files, which rarely carry sentence-transformers metadata; verify the\n        # GGUF is available (below) rather than the ST embedding-metadata gate,\n        # which would wrongly 409 a valid online GGUF embedder.\n        gguf_named = _llama_backend_active() and rag_config._names_gguf(model)\n        if not gguf_named and not is_embedding_model(model, hf_token = hf_token):\n            # Offline, is_embedding_model can only confirm the ST layout (modules.json); a\n            # transformers-native embedder (e.g. gte-modernbert) is unverifiable without Hub\n            # metadata. If already cached and loadable, accept it rather than raising a 409 that\n            # online would not (ST can load any cached encoder). Uncached -> 409.\n            from utils.utils import hf_cache_snapshot_is_loadable\n\n            # Require a genuinely loadable cache (config + weights), not just a resolved refs/main,\n            # so a metadata-only partial cache still gets the forceable 409.\n            offline_cached = local_only_load and hf_cache_snapshot_is_loadable(model)\n            if not offline_cached:\n                raise HTTPException(\n                    status_code = 409,\n                    detail = (\n                        f\"Could not verify {model!r} as an embedding model on \"\n                        \"Hugging Face (it may be the wrong model type, gated, or \"\n                        \"you may be offline).\"\n                    ),\n                )\n        # The Hub GGUF probe (list_repo_files) can hang offline; skip it. Local check stays.\n        gguf_error = _local_gguf_backend_error(model)\n        if gguf_error is None and not local_only_load:\n            gguf_error = _hf_gguf_backend_error(model, hf_token)\n        if gguf_error:\n            raise HTTPException(status_code = 409, detail = gguf_error)\n    set_rag_embedding_model(model)\n    logger.info(\n        \"settings.embedding_model_updated subject=%s model=%s forced=%s\",\n        current_subject,\n        model,","sourceCodeStart":1627,"sourceCodeEnd":1663,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/routes/settings.py#L1627-L1663","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check spelling/org of the model id and that it is actually a sentence-transformers embedding model on the Hub.","If gated: accept the license on Hugging Face and set a valid token via the token endpoint, then retry.","If offline: finish the download (cache must include config + weights), then retry — or go online.","If you know the model is valid (e.g. transformers-native embedder already cached and loadable), resend with force:true to skip verification."],"exampleFix":"# before\nPUT /settings/embedding-model {\"model\": \"BAAI/bge-m3 \"}  # 409, typo/offline\n\n# after\nPUT /settings/embedding-model {\"model\": \"BAAI/bge-m3\"}            # fixed id, online\n# or, trusted non-ST embedder already cached:\nPUT /settings/embedding-model {\"model\": \"Alibaba-NLP/gte-modernbert-base\", \"force\": true}","handlingStrategy":"fallback","validationCode":"const verified = await api.canVerifyEmbeddingModel(model); // or Hub API metadata check\nif (!verified) {\n  await api.put('/settings/embedding-model', { model, force: true }); // only when you trust the model\n} else {\n  await api.put('/settings/embedding-model', { model });\n}","typeGuard":"function needsForce(opts: { offline: boolean; cacheLoadable: boolean; stLayout: boolean }): boolean {\n  return !opts.stLayout && !(opts.offline && opts.cacheLoadable);\n}","tryCatchPattern":"try { await api.put('/settings/embedding-model', { model }); }\ncatch (e) {\n  if (e.status === 409 && /Could not verify/.test(e.detail)) {\n    // wrong type / gated / offline — fix the root cause, or force if trusted:\n    return api.put('/settings/embedding-model', { model, force: true });\n  }\n  throw e;\n}","preventionTips":["Accept gated-model licenses and configure the HF token before switching embedders.","Ensure offline caches are complete (config + weights), not metadata-only.","Double-check org/name spelling against the Hub page."],"tags":["fastapi","http-409","hugging-face","embeddings","offline","validation","gated-model"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}