unslothai/unsloth · error · ValueError

gguf_filename is required: the native engine loads single-fi

Error message

gguf_filename is required: the native engine loads single-file GGUF checkpoints only.

What it means

ValueError from the native backend's begin_load: the sd.cpp engine can only load single-file GGUF checkpoints, so a gguf_filename must accompany repo_id. Direct callers (MCP clients, tests, plugins) that omit it hit this; the route normally validates first.

Source

Thrown at studio/backend/core/inference/sd_cpp_backend.py:1189

        # The ordinal the ROUTE already ranked, so the preflight and the load agree on one card.
        gpu_ordinal: Optional[int] = None,
    ) -> dict[str, Any]:
        """Validate, then fetch assets on a daemon thread. Returns at once."""
        # Empty/whitespace token = "no token"; "" verbatim breaks the anonymous fallback.
        hf_token = hf_token.strip() if hf_token and hf_token.strip() else None
        # Same fallback the diffusers and video backends take: the route ranks the selection and
        # passes the winner, but a direct caller (an MCP client, a test, a plugin) hands over
        # gpu_ids alone, and without this the native engine is the one engine that would drop the
        # pick silently. Re-ranked only when nobody has, so a route-resolved winner is never
        # second-guessed against free VRAM that has moved since.
        if gpu_ordinal is None:
            gpu_ordinal = (
                resolve_selected_cuda_ordinal(gpu_ids)
                if gpu_ids and resolve_diffusion_device_target().device == "cuda"
                else None
            )
        if not gguf_filename:
            raise ValueError(
                "gguf_filename is required: the native engine loads single-file GGUF checkpoints only."
            )
        # Filename-fallback detector (as the route validated) so a local .gguf whose family keyword lives only in the basename still loads.
        fam = detect_family_for_pick(repo_id, gguf_filename, family_override)
        if fam is None:
            raise ValueError(
                f"'{repo_id}' is not a supported diffusion image model. Supported families: "
                f"{', '.join(supported_family_names())}. If this is a variant of one of them, "
                f"pass family_override with that family name."
            )
        if not family_sd_cpp_supported(fam):
            raise ValueError(f"Family '{fam.name}' has no native sd.cpp asset mapping.")

        base = resolve_base_repo(fam, base_repo)
        # Offline-only here, and deliberately so. begin_load returns at once by contract -- the
        # route thread answers the UI with a status and the pull happens on the worker -- so it
        # cannot afford the range request's bound, let alone hold _lock across it and stall
        # status()/unload() for the same span. Memo or on-disk header or nothing. This value only

View on GitHub (pinned to 203007d190)

Solutions

1. Pass the GGUF filename within the repo, e.g. gguf_filename='flux1-schnell-Q8_0.gguf'.
2. List the repo's GGUF files via the Hub API and pick a quant before calling begin_load.
3. If you intended a diffusers-style pipeline load, use the diffusers engine instead of the native one.

Example fix

# before
backend.begin_load(repo_id='city96/FLUX.1-schnell-gguf')

# after
backend.begin_load(repo_id='city96/FLUX.1-schnell-gguf', gguf_filename='flux1-schnell-Q8_0.gguf')

def validate_native_load_kwargs(kwargs: dict) -> None:
    if not kwargs.get('gguf_filename'):
        raise ValueError('gguf_filename is required for the native engine')

def is_valid_native_pick(kwargs: dict) -> bool:
    return bool(kwargs.get('repo_id')) and bool(kwargs.get('gguf_filename'))

When it happens

Trigger: Calling begin_load(repo_id=..., ...) on the native engine without gguf_filename; passing an empty string for gguf_filename.

Common situations: Scripts ported from the diffusers backend where component repos are enough; MCP/plugin callers replicating the route's arguments but dropping gguf_filename.

Related errors

• A gguf/single_file load needs the checkpoint filename.
• a single-file checkpoint name is required for a '{kind}' loa
• a 'gguf' load requires a .gguf checkpoint name.
• a .gguf checkpoint needs model_kind 'gguf', not 'single_file
• Local model path does not exist: {repo_id}

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