{"record":{"id":"faa0b86e52d905fe","repo":"unslothai/unsloth","slug":"repo-id-cannot-be-loaded-excluded","errorCode":null,"errorMessage":"'{repo_id}' cannot be loaded: {excluded}","messagePattern":"'(.+?)' cannot be loaded: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/inference/diffusion.py","lineNumber":1628,"sourceCode":"        *,\n        gguf_filename: Optional[str] = None,\n        family_override: Optional[str] = None,\n        model_kind: Optional[str] = None,\n        base_repo: Optional[str] = None,\n    ) -> DiffusionFamily:\n        \"\"\"Cheap, network-free validation shared by the route (before it evicts the\n        chat model) and the load paths, so an unloadable pick fails BEFORE the GPU\n        handoff. Resolves the load kind (gguf / single_file / pipeline), then raises\n        ValueError for a missing single-file name, a non-unsloth non-GGUF repo, or an\n        undetectable family, and ValueError/FileNotFoundError for a bad local path.\n        Touches no GPU, network, or state.\"\"\"\n        kind = resolve_model_kind(gguf_filename, model_kind)\n        fam = detect_family_for_pick(repo_id, gguf_filename, family_override)\n        if fam is None:\n            # An excluded model gets its stated reason, not the unknown-family message that invites a doomed retry.\n            excluded = excluded_model_reason(repo_id)\n            if excluded:\n                raise ValueError(f\"'{repo_id}' cannot be loaded: {excluded}\")\n            raise ValueError(\n                f\"'{repo_id}' is not a supported diffusion image model. Supported families: \"\n                f\"{', '.join(supported_family_names())}. If this is a variant of one of them, \"\n                f\"pass family_override with that family name. (Video models and image models \"\n                f\"whose diffusers transformer has no single-file loader are not supported.)\"\n            )\n        # Refuse a too-old diffusers here, not deep in the load, but only when this load builds the diffusers pipeline: a\n        # GGUF this host routes to native sd.cpp never instantiates the class. The picker gate reads the same predicate.\n        # Imported here, not at module import, because the router imports this module's siblings.\n        from .diffusion_engine_router import family_buildable_here\n\n        if not family_buildable_here(fam, model_kind = kind):\n            assert_pipeline_class_available(fam.pipeline_class, fam.name)\n        # Families whose single file IS the whole pipeline have no GGUF path; reject before eviction.\n        if kind == \"gguf\" and fam.single_file_is_pipeline:\n            raise ValueError(\n                f\"'{fam.name}' checkpoints are whole-pipeline single files and have no GGUF \"\n                f\"transformer variant; load the .safetensors pipeline instead of a GGUF.\"","sourceCodeStart":1610,"sourceCodeEnd":1646,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/diffusion.py#L1610-L1646","documentation":"Raised by the network-free load validation when family detection returned None and the repo id matches an entry in the _EXCLUDED_MODELS table (matched by whole-segment tokens, so 'kontext' does not match 'kontextual'). Excluded models get their specific stated reason - e.g. an editing/inpaint/layered checkpoint whose transformer needs an extra input - instead of the generic unknown-family message that would invite a doomed retry.","triggerScenarios":"Calling validate_load_request (or the load route that calls it) with a repo_id containing an excluded token - e.g. 'qwen-image-edit', '*-inpaint', 'Qwen-Image-Layered' - without a family_override that resolves to a supported family.","commonSituations":"User browses Hugging Face and picks an edit/inpaint variant of a supported base model (Kontext, layered, inpaint checkpoints share the arch keyword) assuming the base family support covers it; model lists surface variants that the loader cannot feed the extra input image to.","solutions":["Read the reason in the message - it states why this exact variant is unsupported (usually 'needs an input image / different pipeline').","Pick the base (non-edit, non-inpaint, non-layered) checkpoint of the same family instead.","If the variant genuinely is a plain checkpoint with a misleading name, pass family_override with the supported family name to bypass detection.","Do not retry the same id unchanged - exclusion is deliberate and will not resolve on a second attempt."],"exampleFix":"# before: edit variant -> ValueError(\"'org/qwen-image-edit' cannot be loaded: ...\")\nfam = manager.validate_load_request(repo_id=\"org/Qwen-Image-Edit-2511\")\n\n# after: base checkpoint of the same family\nfam = manager.validate_load_request(repo_id=\"org/Qwen-Image\")","handlingStrategy":"validation","validationCode":"from core.inference.diffusion_families import excluded_model_reason\n\ndef pick_is_loadable(repo_id: str) -> bool:\n    return excluded_model_reason(repo_id) is None  # plus family detection for full check","typeGuard":null,"tryCatchPattern":"try:\n    fam = manager.validate_load_request(repo_id=repo_id, model_kind=kind, gguf_filename=fn)\nexcept ValueError as e:\n    if \"cannot be loaded\" in str(e):\n        show_reason_and_suggest_base_checkpoint(repo_id)\n    else:\n        raise","preventionTips":["Filter edit/inpaint/layered variants out of model pickers (keywords: edit, kontext, inpaint, layered) unless you implement their input contract.","Run validate_load_request on every pick before switching models - it is network-free and cheap.","Read the exclusion reason verbatim to the user; it states the structural gap, not a transient failure.","Do not offer family_override as a workaround for excluded models - the override only helps misdetected variants of plain checkpoints."],"tags":["model-validation","unsupported-model","edit-models","diffusion","family-detection"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}