unslothai/unsloth · error · RuntimeError

{fqn}: refusing to pad a quantized Linear whose activation g

Error message

{fqn}: refusing to pad a quantized Linear whose activation granularity is not provably per row. Padding replicates row 0, which is exact only when each kept row's scale is computed from that row alone; under a calibrated or per-tensor activation scale it would silently change every output.

What it means

The quant-pad installer refuses to wrap a quantized nn.Linear in PadToMinM when require_per_row is set and activation_granularity_is_per_row(module) is not provably True. Padding replicates row 0, which is numerically exact only if each row's activation scale was computed per row; under calibrated or per-tensor activation scales, replication would silently corrupt every output, so it is a hard RuntimeError.

Source

Thrown at studio/backend/core/inference/diffusion_quant_pad.py:281

    row raises ``RuntimeError``: see the module docstring for why silence is the wrong answer.
    """
    done: list[str] = []
    for fqn in sorted(set(fqns)):
        parent_name, _, leaf = fqn.rpartition(".")
        try:
            parent = model.get_submodule(parent_name) if parent_name else model
            module = getattr(parent, leaf)
        except AttributeError:
            # A family token that matches nothing on this checkpoint variant is not an error:
            # the pruned and dense H3 trees differ, and callers pass a name list, not a promise.
            continue
        # Skips a dense Linear (``F.linear`` has no row floor to clear, and there is no
        # granularity to prove) and, by the same gate, an already-wrapped one: ``PadToMinM`` is
        # not an ``nn.Linear``, so re-wrapping cannot nest the padding and double the row count.
        if not is_quantized_linear(module):
            continue
        if require_per_row and activation_granularity_is_per_row(module) is not True:
            raise RuntimeError(
                f"{fqn}: refusing to pad a quantized Linear whose activation granularity is not "
                f"provably per row. Padding replicates row 0, which is exact only when each "
                f"kept row's scale is computed from that row alone; under a calibrated or "
                f"per-tensor activation scale it would silently change every output."
            )
        setattr(parent, leaf, PadToMinM(module, min_m = min_m, pad_to = pad_to))
        done.append(fqn)
    return tuple(done)


def matching_linear_fqns(model: nn.Module, name_tokens: Iterable[str]) -> tuple[str, ...]:
    """Every quantized-Linear fqn in ``model`` containing one of ``name_tokens`` (substring,
    case-insensitive) -- the same matching rule ``make_filter_fn`` uses for exclusions, so the
    pad list and the exclude list are read the same way."""
    tokens = tuple(t.lower() for t in name_tokens if t)
    if not tokens:
        return ()
    return tuple(

View on GitHub (pinned to 203007d190)

Solutions

Use a checkpoint whose activation quantization granularity is per-row (standard dynamic per-row scales)
Re-quantize the model without calibration / with per-row activation scales
Skip padding for these Linears (drop their names from the pad target list) if row-count alignment is not needed for them

Defensive patterns

Strategy: validation

Validate before calling

# Before installing pads, verify granularity on each target
fqns = matching_linear_fqns(model, tokens)
for fqn in fqns:
    mod = model.get_submodule(fqn)
    if require_per_row and activation_granularity_is_per_row(mod) is not True:
        skip_or_fail(fqn)  # exclude from the pad list instead of raising

Type guard

def safe_to_pad(module) -> bool:
    return is_quantized_linear(module) and activation_granularity_is_per_row(module) is True

Try / catch

try:
    install_pads(model, targets, require_per_row=True)
except RuntimeError as e:
    if "refusing to pad" in str(e):
        log_and_exclude(e)  # record the fqn, continue without padding it

Prevention

Only apply PadToMinM to dynamically per-row-quantized Linears
Keep calibrated-quant checkpoints out of padded code paths
Treat the refusal as a numerics guard, never catch-and-force

When it happens

Trigger: Calling the pad-install routine (require_per_row=True) on a model whose quantized Linears carry per-tensor or calibrated activation scales instead of per-row — e.g. a checkpoint quantized with a calibration dataset, or a torchao config that used per-tensor input scales.

Common situations: Mixing checkpoints quantized under a different scheme than the padding code assumes; upgrading a quantization tool that changed default activation granularity; hand-modified quant configs.

Related errors

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