unslothai/unsloth · error · RuntimeError

this torch cannot register the pre-quant constructor allowli

Error message

this torch cannot register the pre-quant constructor allowlist (needs torch.serialization.add_safe_globals with (object, name) support, i.e. >= 2.6), so a pre-quant checkpoint cannot be deserialized without allowing arbitrary pickle globals

What it means

_torch_load_prequant refuses to deserialize a pre-quant checkpoint when the installed torch cannot register the constructor allowlist for weights_only loading — torch.serialization.add_safe_globals with (object, name) support, i.e. torch >= 2.6. The alternative (unrestricted pickle) would be remote code execution on a mutated artifact, so an older torch is refused outright, never reopened unrestricted.

Source

Thrown at studio/backend/core/inference/diffusion_prequant.py:278

    floor answer the registration itself already checked."""
    if not _register_prequant_safe_globals():
        return False
    required = _SCHEME_REQUIRED_GLOBALS.get((scheme or "").strip().lower())
    return True if required is None else required <= _RESOLVED_SAFE_GLOBALS


def _torch_load_prequant(path: str, **kwargs: Any) -> Any:
    """``torch.load`` a pre-quant checkpoint under the allowlist above.

    ``weights_only = True`` is the whole point: a pickle that may name any global is remote code
    execution the moment the artifact is not the one that was published. Everything the format
    legitimately needs is allowlisted, so the restriction costs nothing and a mutated artifact
    raises ``UnpicklingError`` into the caller's dense fallback instead of running. A torch that
    cannot express the allowlist is refused outright, never reopened unrestricted."""
    import torch

    if not _register_prequant_safe_globals():
        raise RuntimeError(
            "this torch cannot register the pre-quant constructor allowlist (needs "
            "torch.serialization.add_safe_globals with (object, name) support, i.e. >= 2.6), so "
            "a pre-quant checkpoint cannot be deserialized without allowing arbitrary pickle "
            "globals"
        )
    return torch.load(path, weights_only = True, **kwargs)


_PREQUANT_TOGGLE_TOKENS = {"1", "true", "yes", "on", "0", "false", "no", "off"}


def _allowed_prequant_roots() -> list:
    """Operator-allowlisted directories whose pre-quant checkpoints may be unpickled.

    ``UNSLOTH_ALLOW_LOCAL_PREQUANT_PATH`` = one or more dirs (``os.pathsep``-separated). A
    bare truthy/falsey toggle is ignored: it must name a directory, so no "allow all" mode."""
    import os

View on GitHub (pinned to 203007d190)

Solutions

Upgrade to torch >= 2.6 (pip install -U 'torch>=2.6')
Or convert the checkpoint to .safetensors, which loads without the pickle allowlist
Or use the dense (non-pre-quant) checkpoint variant and quantize at load time

Example fix

// before
torch==2.5.1  # requirements.txt, pre-quant load raises
// after
torch>=2.6.0

Defensive patterns

Strategy: type-guard

Validate before calling

import torch
from packaging.version import Version

def can_load_prequant() -> bool:
    return Version(torch.__version__) >= Version("2.6.0")

Type guard

def prequant_supported() -> bool:
    import torch
    return hasattr(torch.serialization, "add_safe_globals") and Version(torch.__version__.split("+")[0]) >= Version("2.6")

Try / catch

try:
    _torch_load_prequant(path)
except RuntimeError:
    # dense fallback path — do NOT fall back to weights_only=False
    load_dense_checkpoint(path)

Prevention

Pin torch>=2.6 in environments that consume pre-quant checkpoints
Prefer .safetensors artifacts where possible
Never bypass with weights_only=False — the refusal is a security control

When it happens

Trigger: Loading a pre-quant .pt checkpoint (not safetensors) on torch < 2.6 where _register_prequant_safe_globals() returns False. Deliberately raises RuntimeError rather than degrading to weights_only=False.

Common situations: Environments pinned to torch 2.4/2.5 (older CUDA stacks, ROCm builds, CI images); long-lived containers that never upgraded torch.

Related errors

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/bc6f4c7b70c2681a. Report an issue: GitHub.