sgl-project/sglang · error · ValueError

Resolved GGUF path is not a GGUF file: {resolved}

Error message

Resolved GGUF path is not a GGUF file: {resolved}

What it means

After resolving the --transformer-weights-path override (local path, ~-expanded path, or HF reference), the file's magic bytes are checked with check_gguf_file; if it is not a valid GGUF file the load is rejected.

Source

Thrown at python/sglang/multimodal_gen/runtime/loader/transformer_load_utils.py:610

        return None
    # A `~` can reach us unexpanded from a config file or a quoted argument.
    override = os.path.expanduser(override)
    if not names_gguf_checkpoint(override):
        return None

    # Before any download: a Hub reference would otherwise fetch gigabytes and
    # only then hit an unsupported-configuration error.
    _validate_gguf_runtime_support(server_args, component_name)

    is_local_reference = os.path.isabs(override) or override.startswith(".")
    resolved = (
        override
        if is_local_reference
        else resolve_hf_gguf_reference(override, revision=server_args.revision)
        or override
    )
    if not check_gguf_file(resolved):
        raise ValueError(f"Resolved GGUF path is not a GGUF file: {resolved}")
    logger.info("using GGUF transformer weights from: %s", resolved)
    return resolved


def resolve_transformer_safetensors_to_load(
    server_args: ServerArgs, component_model_path: str
) -> list[str]:
    """Resolve transformer weights from the base component path or an override."""
    quantized_path = server_args.transformer_weights_path

    if quantized_path:
        original_quantized_path = quantized_path
        direct_url = _HF_SAFETENSORS_URL_RE.fullmatch(original_quantized_path)
        if direct_url is not None:
            quantized_path = hf_hub_download(
                repo_id=direct_url.group("repo"),
                filename=direct_url.group("filename"),
                revision=direct_url.group("revision"),

View on GitHub (pinned to 0132848349)

Solutions

1. Verify the file is a real GGUF file (e.g. `file model.gguf` or check the GGUF magic bytes)
2. Re-download the checkpoint if it may be truncated/corrupt
3. Point --transformer-weights-path at the correct .gguf file or HF GGUF reference

def is_gguf(path: str) -> bool:
    try:
        with open(path, 'rb') as f:
            return f.read(4) == b'GGUF'
    except OSError:
        return False

if not is_gguf(resolved_path):
    raise SystemExit(f'{resolved_path} is not a valid GGUF file')

def is_gguf(path: str) -> bool:
    try:
        with open(path, 'rb') as f:
            return f.read(4) == b'GGUF'
    except OSError:
        return False

try:
    gguf = resolve_transformer_gguf_to_load(server_args, override)
except ValueError as e:
    logger.error('GGUF resolution failed: %s', e); raise

When it happens

Trigger: resolve_transformer_gguf_to_load resolves the override (locally or via resolve_hf_gguf_reference) but check_gguf_file(resolved) returns False — e.g. pointing at a safetensors/bin file, a corrupt/truncated download, or a wrong HF repo file.

Common situations: Passing a .safetensors or .bin file with a .gguf-looking flag, a partially downloaded file, or an HF repo id that resolves to a non-GGUF weight file.

Related errors

• A GGUF encoder checkpoint cannot be combined with a second q
• GGUF tensor {tensor.name} declares original shape {logical_s
• GGUF tensors collide after parameter mapping at {alias!r}
• scale_shift_table must have shape [9, D]
• SGLang diffusion currently supports AutoRound auto_gptq chec

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/5723354faeae6835. Report an issue: GitHub.