unslothai/unsloth · error · ValueError

'{repo_id}' is a GGUF repo: pick one of its .gguf files (ggu

Error message

'{repo_id}' is a GGUF repo: pick one of its .gguf files (gguf_filename) instead of loading it as a diffusers pipeline.

What it means

Validation refuses loading a GGUF-hosting repo (name ending in '-gguf', case-insensitive, trailing slash tolerated) as a diffusers pipeline without selecting a quant file. Such repos have no pipeline layout; without this gate the request would resolve to kind 'pipeline' and only blow up inside from_pretrained after the resident model was evicted.

Source

Thrown at studio/backend/core/inference/video.py:1070

    # ── validation ───────────────────────────────────────────────────────────

    def validate_load_request(
        self,
        repo_id: str,
        *,
        gguf_filename: Optional[str] = None,
        base_repo: Optional[str] = None,
        family_override: Optional[str] = None,
        model_kind: Optional[str] = None,
        transformer_quant: Optional[str] = None,
        text_encoder_quant: Optional[str] = None,
        h3_task: Optional[str] = None,
    ) -> VideoFamily:
        """Cheap, network-free validation shared by the route and the load path."""
        kind = resolve_video_model_kind(gguf_filename, model_kind)
        # A -GGUF repo picked without a quant filename resolves to pipeline kind and would only fail in from_pretrained after eviction.
        if kind == "pipeline" and repo_id.strip().lower().rstrip("/").endswith("-gguf"):
            raise ValueError(
                f"'{repo_id}' is a GGUF repo: pick one of its .gguf files "
                "(gguf_filename) instead of loading it as a diffusers pipeline."
            )
        fam = _detect_load_family(repo_id, gguf_filename, family_override)
        if fam is None:
            raise ValueError(
                f"'{repo_id}' is not a supported text-to-video model. Supported families: "
                f"{', '.join(supported_video_family_names())}. If this is a variant of one "
                f"of them, pass family_override with that family name."
            )
        # ── modular-workflow refusals, before anything heavier.
        # Deliberately the FIRST thing after the family resolves: everything below reaches into
        # diffusers (assert_pipeline_class_available, the transformer_class probe), so a refusal
        # placed after them would be unreachable on any install whose diffusers cannot even be
        # imported -- and these two are exactly the picks that cost the most to discover late.
        if fam.modular_workflow and kind == "single_file":
            # A modular workflow has no single-file assembly: its components each load through
            # their own from_pretrained from the modular index, and nothing consumes a lone

View on GitHub (pinned to 203007d190)

Solutions

1. Pick a specific quant: pass gguf_filename='...-Q4_K_M.gguf' from that repo.
2. Or load the original diffusers pipeline repo (drop the '-GGUF' suffix / use the base repo id).
3. If scripting, list the repo's files first and choose a .gguf whose size fits your VRAM.

Example fix

# before
load_video_model(repo_id='city96/HunyuanVideo-GGUF')

# after
load_video_model(repo_id='city96/HunyuanVideo-GGUF', gguf_filename='hunyuan-video-t2v-720p-Q4_K_M.gguf')

def is_gguf_repo(repo_id: str) -> bool:
    return repo_id.strip().lower().rstrip('/').endswith('-gguf')

def needs_gguf_filename(repo_id: str, gguf_filename: str | None, model_kind: str | None) -> bool:
    kind = (model_kind or '').strip().lower() or ('gguf' if (gguf_filename or '').lower().endswith('.gguf') else '')
    resolves_pipeline = not gguf_filename and not kind
    return resolves_pipeline and repo_id.strip().lower().rstrip('/').endswith('-gguf')

try:
    load_video_model(repo_id=repo)
except ValueError as e:
    if 'is a GGUF repo' in str(e):
        files = list_repo_files(repo)
        gguf = pick_quant(files)
        load_video_model(repo_id=repo, gguf_filename=gguf)
    else:
        raise

When it happens

Trigger: Calling the video load route with repo_id like 'Fooocus/hunyuan-video-GGUF' (ends with '-gguf') and no gguf_filename and no model_kind override.

Common situations: Pasting a GGUF repo URL from a model hub into the pipeline repo field; forgetting the second step (file picker) of a GGUF load; assuming the backend auto-picks the lone .gguf file in the repo.

Related errors

• Unknown model_kind '{model_kind}'. Expected one of {sorted(_
• '{fam.name}' cannot load from a single .safetensors checkpoi
• '{Path(gguf_filename or '').name}' is the {picked} partition
• base_repo is limited to unsloth/* repos, the official family
• A gguf/single_file load needs the checkpoint filename.

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