unslothai/unsloth · error · ValueError

'{fam.name}' cannot load from a single .safetensors checkpoi

Error message

'{fam.name}' cannot load from a single .safetensors checkpoint: it is assembled by its Modular Diffusers workflow, which builds every component from a repo. Load the diffusers pipeline repo '{fam.base_repo}' for the full bfloat16 model{gguf_hint}.

What it means

A modular-workflow family (e.g. the H3 pipeline assembled by Modular Diffusers) cannot be loaded from a single .safetensors DiT checkpoint: its components are each built from a repo via the modular index, and nothing consumes a lone DiT file. The gate exists because the failure otherwise surfaces only after ~98.7 GB of downloads and after the resident pipeline was torn down.

Source

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

                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
            # .safetensors DiT. Today that only surfaces inside the loader, i.e. after ~98.7 GB
            # has downloaded AND after the resident pipeline was torn down to make room for it.
            gguf_hint = (
                f", or a .gguf checkpoint from '{fam.gguf_repo}' for a quantized single-file load"
                if fam.gguf_repo
                else ""
            )
            raise ValueError(
                f"'{fam.name}' cannot load from a single .safetensors checkpoint: it is assembled "
                f"by its Modular Diffusers workflow, which builds every component from a repo. "
                f"Load the diffusers pipeline repo '{fam.base_repo}' for the full bfloat16 "
                f"model{gguf_hint}."
            )
        if fam.modular_workflow and kind == "pipeline":
            # Metal cannot place a modular workflow at all. _load_h3_modular_pipeline hands every
            # non-CPU device to ComponentsManager.enable_auto_cpu_offload, which reads
            # torch.<device>.mem_get_info and raises NotImplementedError for a device module
            # without one; torch.mps has never exposed it. Refuse here, before ~145 GB downloads
            # and the resident pipeline is torn down to make room for it.
            if resolve_diffusion_device_target().device == "mps":
                gguf_hint = (
                    f" Load a .gguf checkpoint from '{fam.gguf_repo}' instead, which runs on the "
                    f"native engine."
                    if fam.gguf_repo
                    else ""
                )

View on GitHub (pinned to 203007d190)

Solutions

Load the family's full diffusers pipeline repo (fam.base_repo) for the bf16 model.
If you want a single quantized file, load a .gguf checkpoint from fam.gguf_repo instead (the message appends this hint when one exists).
Do not pass a lone .safetensors filename for modular-workflow families.

Example fix

# before
load_video_model(repo_id=..., gguf_filename='transformer.safetensors')  # single_file + modular family

# after
load_video_model(repo_id='<family base_repo>')  # full pipeline
# or quantized single file:
load_video_model(repo_id='<gguf_repo>', gguf_filename='model-Q4_K_M.gguf')

Defensive patterns

Strategy: validation

Validate before calling

fam = _detect_load_family(repo_id, gguf_filename, family_override)
kind = resolve_video_model_kind(gguf_filename, model_kind)
single_file_conflict = fam is not None and getattr(fam, 'modular_workflow', False) and kind == 'single_file'
# if single_file_conflict: request fam.base_repo (pipeline) or fam.gguf_repo (gguf) instead

Try / catch

try:
    load_video_model(repo_id=r, gguf_filename=f)
except ValueError as e:
    if 'cannot load from a single .safetensors' in str(e):
        load_video_model(repo_id=r)  # full pipeline repo
    else:
        raise

Prevention

Mark modular-workflow families in the UI as 'pipeline/GGUF only'.
Never hand a lone transformer .safetensors to a modular family's loader.
Check fam.modular_workflow and fam.gguf_repo before building load options.

When it happens

Trigger: Resolving kind to 'single_file' (a non-.gguf filename given, or model_kind='single_file') while the detected family has modular_workflow=True.

Common situations: Downloading just the transformer .safetensors from a modular repo to save space and pointing the loader at it; UI flows designed for classic single-file families (Wan etc.) applied to a modular one; assuming a .safetensors DiT plus config can be hand-assembled.

Related errors

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