{"record":{"id":"f865b578c0e3897c","repo":"unslothai/unsloth","slug":"family-name-needs-diffusers-pipeline-class-f865b5","errorCode":null,"errorMessage":"'{family_name}' needs diffusers ({pipeline_class}), but this diffusers exports it as a placeholder, which it does when a backend it requires is unavailable. That class requires: {', '.join(dummy_backends)}. Check which of those this environment is missing and install it.","messagePattern":"'(.+?)' needs diffusers \\((.+?)\\), but this diffusers exports it as a placeholder, which it does when a backend it requires is unavailable\\. That class requires: (.+?)\\. Check which of those this environment is missing and install it\\.","errorType":"exception","errorClass":"ValueError","httpStatus":400,"severity":"error","filePath":"studio/backend/core/inference/diffusion_families.py","lineNumber":1160,"sourceCode":"        # The attribute probe is inside the try for the same reason. diffusers' top level is a lazy module, so\n        # ``hasattr`` is what actually imports the pipeline's submodule, and when that submodule's own dependencies\n        # are unsatisfiable it raises RuntimeError (\"Failed to import diffusers.pipelines...\") -- which hasattr does\n        # NOT swallow, since it only absorbs AttributeError. A partially usable diffusers install therefore escaped\n        # this guard exactly the way a missing one used to.\n        if strict:\n            raise ValueError(\n                f\"'{family_name}' needs diffusers ({pipeline_class}), which this environment \"\n                f\"cannot import: {exc}. Install or repair it with: pip install -U diffusers.\"\n            ) from None\n        return\n\n    if present and dummy_backends:\n        # A placeholder, not the pipeline. Under the default this is left alone like every other\n        # unusable install; strict refuses, because the trainer child imports the same placeholder\n        # and its from_pretrained raises only after the GPU residents are gone.\n        if not strict:\n            return\n        raise ValueError(\n            f\"'{family_name}' needs diffusers ({pipeline_class}), but this diffusers exports it as \"\n            f\"a placeholder, which it does when a backend it requires is unavailable. That class \"\n            f\"requires: {', '.join(dummy_backends)}. Check which of those this environment is \"\n            f\"missing and install it.\"\n        )\n\n    if present:\n        return\n    raise ValueError(\n        _too_old_message(\n            pipeline_class, family_name, str(getattr(diffusers, \"__version__\", \"unknown\"))\n        )\n    )\n\n\ndef family_probe_class(fam: Any) -> str:\n    \"\"\"The class whose presence in the installed diffusers actually proves ``fam`` is loadable.\n","sourceCodeStart":1142,"sourceCodeEnd":1178,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/diffusion_families.py#L1142-L1178","documentation":"diffusers imports and exports the family's pipeline class, but as a placeholder ('dummy') object — the class diffusers substitutes when an optional backend it requires (torch, transformers, etc.) is unavailable at diffusers' own import time. Strict mode refuses before training, because the trainer child would import the same placeholder and its from_pretrained would fail only after the GPU residents were freed. The message lists exactly which backends that class requires.","triggerScenarios":"Training a family whose pipeline_class exists on diffusers but _dummy_required_backends() reports non-empty backends — typically an incompatible/downgraded torch or transformers relative to the installed diffusers, so diffusers could not construct the real pipeline class.","commonSituations":"Downgrading torch for another component leaves diffusers' backend check unsatisfied; a fresh venv where transformers is missing or too old; mixing pip and conda installs so diffusers sees a different torch; environments pinned to older backends than the new families (Flux2Klein, Z-Image, LTX-2, ...) require.","solutions":["Read the message's required-backends list and install/upgrade the named one(s), usually: pip install -U torch transformers","Then verify the placeholder is gone: python -c \"import diffusers; print(type(diffusers.<PipelineClass>))\" — it must not be a DummyObject","If constraints force the old backend, downgrade diffusers to a version whose requirements match, and drop the new-family pick","Re-run the training request after repairing the environment"],"exampleFix":"# before\n# torch too old for installed diffusers -> dummy pipeline class -> ValueError\n\n# after\npip install -U torch transformers   # the backends named in the message\npython -c \"import diffusers, torch; print(type(diffusers.FluxPipeline))\"  # real class, not DummyObject","handlingStrategy":"validation","validationCode":"def pipeline_class_real(pipeline_class: str) -> bool:\n    try:\n        import diffusers\n        from diffusers.utils.dummy_pt_objects import DummyObject  # or equivalent dummy base\n        cls = getattr(diffusers, pipeline_class, None)\n        return cls is not None and not isinstance(cls, type) or (\n            isinstance(cls, type) and not issubclass(cls, DummyObject)\n        )\n    except Exception:\n        return False","typeGuard":null,"tryCatchPattern":"try:\n    validate_family_pipeline(pipeline_class, family_name, strict=True)\nexcept ValueError as e:\n    # message names the exact missing backends; install them before retrying training\n    return bad_request(str(e))","preventionTips":["Pin torch/transformers/diffusers to a mutually compatible set; verify after every upgrade","After installing, confirm the class is real: type(diffusers.<PipelineClass>) must not be a dummy","Avoid mixing pip and conda installs — a diffusers that sees the wrong torch silently exports placeholders"],"tags":["diffusers","dependency","environment","training","version-mismatch"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}