{"record":{"id":"9ef6be10646842d0","repo":"unslothai/unsloth","slug":"gguf-filename-is-required-the-native-engine-loads","errorCode":null,"errorMessage":"gguf_filename is required: the native engine loads single-file GGUF checkpoints only.","messagePattern":"gguf_filename is required: the native engine loads single-file GGUF checkpoints only\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/inference/sd_cpp_backend.py","lineNumber":1189,"sourceCode":"        # The ordinal the ROUTE already ranked, so the preflight and the load agree on one card.\n        gpu_ordinal: Optional[int] = None,\n    ) -> dict[str, Any]:\n        \"\"\"Validate, then fetch assets on a daemon thread. Returns at once.\"\"\"\n        # Empty/whitespace token = \"no token\"; \"\" verbatim breaks the anonymous fallback.\n        hf_token = hf_token.strip() if hf_token and hf_token.strip() else None\n        # Same fallback the diffusers and video backends take: the route ranks the selection and\n        # passes the winner, but a direct caller (an MCP client, a test, a plugin) hands over\n        # gpu_ids alone, and without this the native engine is the one engine that would drop the\n        # pick silently. Re-ranked only when nobody has, so a route-resolved winner is never\n        # second-guessed against free VRAM that has moved since.\n        if gpu_ordinal is None:\n            gpu_ordinal = (\n                resolve_selected_cuda_ordinal(gpu_ids)\n                if gpu_ids and resolve_diffusion_device_target().device == \"cuda\"\n                else None\n            )\n        if not gguf_filename:\n            raise ValueError(\n                \"gguf_filename is required: the native engine loads single-file GGUF checkpoints only.\"\n            )\n        # Filename-fallback detector (as the route validated) so a local .gguf whose family keyword lives only in the basename still loads.\n        fam = detect_family_for_pick(repo_id, gguf_filename, family_override)\n        if fam is None:\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.\"\n            )\n        if not family_sd_cpp_supported(fam):\n            raise ValueError(f\"Family '{fam.name}' has no native sd.cpp asset mapping.\")\n\n        base = resolve_base_repo(fam, base_repo)\n        # Offline-only here, and deliberately so. begin_load returns at once by contract -- the\n        # route thread answers the UI with a status and the pull happens on the worker -- so it\n        # cannot afford the range request's bound, let alone hold _lock across it and stall\n        # status()/unload() for the same span. Memo or on-disk header or nothing. This value only","sourceCodeStart":1171,"sourceCodeEnd":1207,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/sd_cpp_backend.py#L1171-L1207","documentation":"ValueError from the native backend's begin_load: the sd.cpp engine can only load single-file GGUF checkpoints, so a gguf_filename must accompany repo_id. Direct callers (MCP clients, tests, plugins) that omit it hit this; the route normally validates first.","triggerScenarios":"Calling begin_load(repo_id=..., ...) on the native engine without gguf_filename; passing an empty string for gguf_filename.","commonSituations":"Scripts ported from the diffusers backend where component repos are enough; MCP/plugin callers replicating the route's arguments but dropping gguf_filename.","solutions":["Pass the GGUF filename within the repo, e.g. gguf_filename='flux1-schnell-Q8_0.gguf'.","List the repo's GGUF files via the Hub API and pick a quant before calling begin_load.","If you intended a diffusers-style pipeline load, use the diffusers engine instead of the native one."],"exampleFix":"# before\nbackend.begin_load(repo_id='city96/FLUX.1-schnell-gguf')\n\n# after\nbackend.begin_load(repo_id='city96/FLUX.1-schnell-gguf', gguf_filename='flux1-schnell-Q8_0.gguf')","handlingStrategy":"validation","validationCode":"def validate_native_load_kwargs(kwargs: dict) -> None:\n    if not kwargs.get('gguf_filename'):\n        raise ValueError('gguf_filename is required for the native engine')","typeGuard":"def is_valid_native_pick(kwargs: dict) -> bool:\n    return bool(kwargs.get('repo_id')) and bool(kwargs.get('gguf_filename'))","tryCatchPattern":null,"preventionTips":["Always pair repo_id with gguf_filename for native loads.","Keep a single argument-builder shared by load, plan and route code so the pick is validated once."],"tags":["validation","api-usage","gguf","sd-cpp"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}