{"record":{"id":"10badaf00b45b206","repo":"mudler/LocalAI","slug":"failed-to-load-pipeline-pipeline-class-name","errorCode":null,"errorMessage":"Failed to load pipeline '{pipeline_class.__name__}' from '{model_id}': {e}\\nAvailable pipelines: {', '.join(available[:20])}...","messagePattern":"Failed to load pipeline '(.+?)' from '(.+?)': (.+?)\\\\nAvailable pipelines: (.+?)\\.\\.\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"backend/python/diffusers/diffusers_dynamic_loader.py","lineNumber":499,"sourceCode":"\n    # Load the pipeline\n    try:\n        if from_single_file:\n            # Check if the class has from_single_file method\n            if hasattr(pipeline_class, 'from_single_file'):\n                return pipeline_class.from_single_file(model_id, **kwargs)\n            else:\n                raise ValueError(\n                    f\"Pipeline class {pipeline_class.__name__} does not support from_single_file(). \"\n                    f\"Use from_pretrained() instead.\"\n                )\n        else:\n            return pipeline_class.from_pretrained(model_id, **kwargs)\n\n    except Exception as e:\n        # Provide helpful error message\n        available = get_available_pipelines()\n        raise RuntimeError(\n            f\"Failed to load pipeline '{pipeline_class.__name__}' from '{model_id}': {e}\\n\"\n            f\"Available pipelines: {', '.join(available[:20])}...\"\n        ) from e\n\n\ndef get_pipeline_info(class_name: str) -> Dict[str, Any]:\n    \"\"\"\n    Get information about a specific pipeline class.\n\n    Args:\n        class_name: The pipeline class name\n\n    Returns:\n        Dictionary with pipeline information including:\n        - name: Class name\n        - aliases: List of task aliases\n        - supports_single_file: Whether from_single_file() is available\n        - docstring: Class docstring (if available)","sourceCodeStart":481,"sourceCodeEnd":517,"githubUrl":"https://github.com/mudler/LocalAI/blob/44413a9d06bf5bc52ce088ba8ca74e5a2e8bee26/backend/python/diffusers/diffusers_dynamic_loader.py#L481-L517","documentation":"Raised by load_diffusers_pipeline when pipeline_class.from_single_file() or from_pretrained() throws during the actual weight load. It wraps the original exception (chained with `from e`), names the class and model_id, and appends up to 20 available pipeline names as a corrective hint.","triggerScenarios":"Weight loading fails: missing/corrupt files in the model directory, auth-gated HuggingFace repo without a token, network failure fetching from the hub, dtype/variant mismatch (e.g. requesting fp16 variant that was not downloaded), or out-of-memory while initializing modules.","commonSituations":"Model directory incomplete (partial download), HF_TOKEN missing for gated models like SDXL/Flux, no network in an air-gapped deployment with local_only semantics, or insufficient VRAM/RAM during pipeline init.","solutions":["Read the chained exception — the root cause (HTTP 401, FileNotFoundError, OOM) determines the fix; the pipeline list is secondary.","For gated repos, provide a valid HuggingFace token in the environment/config.","Verify the snapshot contents match the pipeline's expected file layout; re-download if incomplete.","For OOM, pass torch_dtype=float16 / enable cpu offload via load_kwargs, or free other GPU processes first."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"import os\nif os.path.isdir(model_id):\n    missing = [f for f in ('model_index.json',) if not os.path.isfile(os.path.join(model_id, f))]\n    assert not missing, f\"incomplete diffusers snapshot: missing {missing}\"\nelif os.path.isfile(model_id):\n    assert model_id.endswith(('.ckpt', '.safetensors')), 'not a single-file checkpoint'","typeGuard":null,"tryCatchPattern":"try:\n    pipe = load_diffusers_pipeline(class_name=c, model_id=m, **kw)\nexcept RuntimeError as e:\n    cause = e.__cause__  # original from_pretrained exception carries the real reason\n    if isinstance(cause, (OSError, ConnectionError)):\n        return error_reply(\"model download/conn issue; check network or HF token\")\n    if isinstance(cause, MemoryError) or 'out of memory' in str(cause).lower():\n        return error_reply(\"OOM loading pipeline; try fp16 or a smaller model\")\n    return error_reply(str(e))","preventionTips":["Set HF_TOKEN for gated repos before backend start.","Pre-download models in deployment so runtime loads are local-only.","Inspect e.__cause__ — the wrapper message alone rarely names the root problem."],"tags":["diffusers","model-loading","huggingface","resource-exhaustion"],"backgroundTag":null,"analyzedSha":"44413a9d06bf5bc52ce088ba8ca74e5a2e8bee26","analyzedAt":"2026-08-15T10:13:50.291Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}