{"record":{"id":"89415dbc9fb7a8d5","repo":"unslothai/unsloth","slug":"fam-name-cannot-load-from-a-single-safetensor","errorCode":null,"errorMessage":"'{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}.","messagePattern":"'(.+?)' 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 '(.+?)' for the full bfloat16 model(.+?)\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/inference/video.py","lineNumber":1096,"sourceCode":"                f\"{', '.join(supported_video_family_names())}. If this is a variant of one \"\n                f\"of them, pass family_override with that family name.\"\n            )\n        # ── modular-workflow refusals, before anything heavier.\n        # Deliberately the FIRST thing after the family resolves: everything below reaches into\n        # diffusers (assert_pipeline_class_available, the transformer_class probe), so a refusal\n        # placed after them would be unreachable on any install whose diffusers cannot even be\n        # imported -- and these two are exactly the picks that cost the most to discover late.\n        if fam.modular_workflow and kind == \"single_file\":\n            # A modular workflow has no single-file assembly: its components each load through\n            # their own from_pretrained from the modular index, and nothing consumes a lone\n            # .safetensors DiT. Today that only surfaces inside the loader, i.e. after ~98.7 GB\n            # has downloaded AND after the resident pipeline was torn down to make room for it.\n            gguf_hint = (\n                f\", or a .gguf checkpoint from '{fam.gguf_repo}' for a quantized single-file load\"\n                if fam.gguf_repo\n                else \"\"\n            )\n            raise ValueError(\n                f\"'{fam.name}' cannot load from a single .safetensors checkpoint: it is assembled \"\n                f\"by its Modular Diffusers workflow, which builds every component from a repo. \"\n                f\"Load the diffusers pipeline repo '{fam.base_repo}' for the full bfloat16 \"\n                f\"model{gguf_hint}.\"\n            )\n        if fam.modular_workflow and kind == \"pipeline\":\n            # Metal cannot place a modular workflow at all. _load_h3_modular_pipeline hands every\n            # non-CPU device to ComponentsManager.enable_auto_cpu_offload, which reads\n            # torch.<device>.mem_get_info and raises NotImplementedError for a device module\n            # without one; torch.mps has never exposed it. Refuse here, before ~145 GB downloads\n            # and the resident pipeline is torn down to make room for it.\n            if resolve_diffusion_device_target().device == \"mps\":\n                gguf_hint = (\n                    f\" Load a .gguf checkpoint from '{fam.gguf_repo}' instead, which runs on the \"\n                    f\"native engine.\"\n                    if fam.gguf_repo\n                    else \"\"\n                )","sourceCodeStart":1078,"sourceCodeEnd":1114,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/video.py#L1078-L1114","documentation":"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.","triggerScenarios":"Resolving kind to 'single_file' (a non-.gguf filename given, or model_kind='single_file') while the detected family has modular_workflow=True.","commonSituations":"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.","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."],"exampleFix":"# before\nload_video_model(repo_id=..., gguf_filename='transformer.safetensors')  # single_file + modular family\n\n# after\nload_video_model(repo_id='<family base_repo>')  # full pipeline\n# or quantized single file:\nload_video_model(repo_id='<gguf_repo>', gguf_filename='model-Q4_K_M.gguf')","handlingStrategy":"validation","validationCode":"fam = _detect_load_family(repo_id, gguf_filename, family_override)\nkind = resolve_video_model_kind(gguf_filename, model_kind)\nsingle_file_conflict = fam is not None and getattr(fam, 'modular_workflow', False) and kind == 'single_file'\n# if single_file_conflict: request fam.base_repo (pipeline) or fam.gguf_repo (gguf) instead","typeGuard":null,"tryCatchPattern":"try:\n    load_video_model(repo_id=r, gguf_filename=f)\nexcept ValueError as e:\n    if 'cannot load from a single .safetensors' in str(e):\n        load_video_model(repo_id=r)  # full pipeline repo\n    else:\n        raise","preventionTips":["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."],"tags":["video","modular-workflow","model-config","validation"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}