{"record":{"id":"3b4670f9df4f2cf2","repo":"unslothai/unsloth","slug":"gguf-variant-variant-not-found-in-identifier","errorCode":null,"errorMessage":"GGUF variant '{variant}' not found in {identifier}. Available variants: {available}","messagePattern":"GGUF variant '(.+?)' not found in (.+?)\\. Available variants: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":400,"severity":"error","filePath":"studio/backend/utils/models/model_config.py","lineNumber":3859,"sourceCode":"\n                    # Reject before the load path unloads the resident model.\n                    # Only a live, complete repo listing can prove the variant\n                    # absent; without one, let the load path resolve it. The\n                    # cache escape mirrors the load path's own reuse predicate.\n                    try:\n                        from huggingface_hub import list_repo_files\n                        repo_files = list_repo_files(identifier, token = hf_token)\n                    except Exception:\n                        repo_files = None\n                    if (\n                        repo_files\n                        and not _gguf_files_for_variant(repo_files, variant)\n                        and not cached_gguf_for_load(\n                            identifier, variant, verify_sizes = True, hf_token = hf_token\n                        )\n                    ):\n                        available = \", \".join(v.quant for v in variants)\n                        raise ValueError(\n                            f\"GGUF variant '{variant}' not found in {identifier}. \"\n                            f\"Available variants: {available}\"\n                        )\n                if not variant:  # auto-select best quant\n                    # ROOT rows when there are any. _pick_best_gguf keeps whichever filename it\n                    # met first among equals, so an LTX-style listing that puts distilled/...-Q6_K\n                    # before the root ...-Q6_K made a bare repo id load the distilled checkpoint --\n                    # while local_model_resolver, the auto-download map and /gguf-variants all\n                    # define a bare id as the root. This is the LOAD path, so it has to agree.\n                    root_rows = [\n                        v.filename\n                        for v in variants\n                        if \"/\" not in _qualified_variant_name(v.filename, v.quant)\n                    ]\n                    variant_filenames = root_rows or [v.filename for v in variants]\n                    best = _pick_best_gguf(variant_filenames)\n                    if best:\n                        # The SAME identity the lister advertised for that file. Converting the","sourceCodeStart":3841,"sourceCodeEnd":3877,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/utils/models/model_config.py#L3841-L3877","documentation":"When the caller explicitly requests a GGUF variant (quant) for a repo, the code lists repo files and asks _gguf_files_for_variant() whether that variant exists; if neither the live listing nor a verified local cache (cached_gguf_for_load with verify_sizes=True) contains it, it raises with the variants actually available (their quant names) so the user can immediately re-pick. The preflight exists to reject before the load path unloads the resident model.","triggerScenarios":"Passing gguf_variant='Q4_K_M' when the repo only ships Q8_0/Q6_K (or uses a naming scheme _gguf_files_for_variant does not map to that quant token); the requested variant's local copy is size-mismatched so verify_sizes rejects the cache fallback. A network failure in list_repo_files is tolerated (repo_files=None) and does NOT raise here.","commonSituations":"Hardcoding a quant from a different model card; repos with distilled/split GGUFs whose names parse to unexpected quants; requesting a variant deleted upstream while a stale UI list still shows it; interrupted downloads leaving incomplete cached files.","solutions":["Read the message's 'Available variants' list and re-request one of those (or drop gguf_variant to auto-select the best quant)","If you expected the variant, check the repo page for renamed/split files (e.g. '-00001-of-00002.gguf') and pass the exact quant token the listing uses","Delete the partial cached GGUF and retry, so a size-verified redownload can satisfy the cache fallback","Call the /gguf-variants endpoint for the identifier to see the canonical variant list before loading"],"exampleFix":"# before\nload_model('org/model-GGUF', gguf_variant='Q4_K_M')\n# ValueError: GGUF variant 'Q4_K_M' not found ... Available variants: Q6_K, Q8_0\n\n# after\nload_model('org/model-GGUF', gguf_variant='Q6_K')\n# or auto-select\nload_model('org/model-GGUF')","handlingStrategy":"validation","validationCode":"from utils.models.model_config import list_gguf_variants\n\ndef variant_valid(identifier: str, variant: str, hf_token=None) -> bool:\n    variants, _ = list_gguf_variants(identifier, hf_token=hf_token)\n    return variant in {v.quant for v in variants}","typeGuard":null,"tryCatchPattern":"try:\n    load_model(repo_id, gguf_variant=v)\nexcept ValueError as e:\n    if 'Available variants:' in str(e):\n        offered = parse_variants(str(e))\n        v = pick_from(offered)  # re-request with a valid quant or None for auto\n    else:\n        raise","preventionTips":["Populate variant pickers from /gguf-variants for the exact repo","Omit gguf_variant to auto-select the best quant instead of hardcoding","Re-check the model card when upstream quants are renamed or removed"],"tags":["gguf","quantization","huggingface","variant-selection","preflight"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}