unslothai/unsloth · error · ValueError

Unknown model_kind '{model_kind}'. Expected one of {sorted(_

Error message

Unknown model_kind '{model_kind}'. Expected one of {sorted(_MODEL_KINDS)}.

What it means

Raised by resolve_model_kind in the diffusion module when an explicit model_kind string is passed but, after strip().lower(), it is not one of _MODEL_KINDS (which include at least 'pipeline', 'gguf', 'single_file'). It is a request-validation error: the client-supplied kind must match the module's vocabulary exactly.

Source

Thrown at studio/backend/core/inference/diffusion.py:263

    where = f"https://huggingface.co/{repo}" if repo else "its Hugging Face page"
    subject = repo or "This model"
    if had_token:
        # A token was sent and still bounced, so the account itself lacks access.
        return f"{subject} is gated and this Hugging Face account is not on its access list. Request access at {where}, then load again."
    return f"{subject} is gated. Request access at {where}, then add a Hugging Face token in Settings and load again."


def resolve_model_kind(gguf_filename: Optional[str], model_kind: Optional[str] = None) -> str:
    """Classify a load request into one of ``_MODEL_KINDS``.

    An explicit ``model_kind`` wins (validated). Otherwise the kind is inferred from
    the single-file name: a ``.gguf`` name is ``"gguf"``, any other single-file name is
    ``"single_file"``, and the absence of a name is a full ``"pipeline"`` load. Pure and
    network-free, so the route, validation, and load paths all agree on the kind."""
    if model_kind:
        kind = model_kind.strip().lower()
        if kind not in _MODEL_KINDS:
            raise ValueError(
                f"Unknown model_kind '{model_kind}'. Expected one of {sorted(_MODEL_KINDS)}."
            )
        return kind
    name = (gguf_filename or "").strip()
    if not name:
        return "pipeline"
    if name.lower().endswith(".gguf"):
        return "gguf"
    return "single_file"


def _active_lora_pairs(pipe: Any) -> list:
    """``[(name, weight)]`` for the adapters actually attached to ``pipe``, zero-weight ones
    dropped.

    Reads the ``_unsloth_loras`` marker, which the LoRA paths write as ``(name, path, weight)``.
    Shape is tolerated rather than assumed: this runs inside the generate result and an unpacking
    error here would sink a finished generation whose images are already in hand."""

View on GitHub (pinned to 203007d190)

Solutions

Use one of the exact values listed in the error message (it prints sorted(_MODEL_KINDS))
Omit model_kind entirely to let it infer from gguf_filename: '.gguf' name → 'gguf', other name → 'single_file', no name → 'pipeline'
Align client and backend versions so the enum vocabulary matches

Example fix

# before
{"model_kind": "diffusers", "repo_id": "..."}

# after
{"model_kind": "pipeline", "repo_id": "..."}

Defensive patterns

Strategy: validation

Validate before calling

MODEL_KINDS = {"pipeline", "gguf", "single_file"}  # mirror _MODEL_KINDS
def valid_model_kind(kind: str | None) -> bool:
    return kind is None or kind.strip().lower() in MODEL_KINDS

Type guard

def is_model_kind(v: str) -> bool:
    import typing
    return isinstance(v, str) and v.strip().lower() in {"pipeline", "gguf", "single_file"}

Try / catch

try:
    kind = resolve_model_kind(gguf_filename, model_kind)
except ValueError as e:
    if "Unknown model_kind" in str(e):
        return JSONResponse(status_code=422, content={"detail": str(e)})

Prevention

Let the server infer the kind from gguf_filename instead of sending one
Fetch the allowed kinds from the API schema rather than hardcoding
Keep frontend and backend enum vocabularies in sync on deploy

When it happens

Trigger: POSTing a diffusion load request with model_kind like 'diffusers', 'ckpt', 'gguf-file', or a typo/'GGUF ' variant that lowercases fine but a misspelled value; client and backend versions disagreeing on the allowed kinds.

Common situations: Frontend deployed ahead of/behind the backend so it sends a new or old kind name; hand-written API calls guessing the enum; stale cached form state after the vocabulary changed.

Related errors

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