unslothai/unsloth · error · ValueError

unsupported activation rotation {kind!r} (this build impleme

Error message

unsupported activation rotation {kind!r} (this build implements {CONVROT_KIND!r})

What it means

At load time, apply_activation_rotation read a rotation 'kind' from checkpoint metadata that this build does not implement (only CONVROT_KIND is supported). The checkpoint was produced by a builder using a different rotation scheme, so this build refuses rather than applying a rotation it cannot undo or verify.

Source

Thrown at studio/backend/core/inference/diffusion_convrot.py:344

    logger: Any = None,
) -> tuple[str, ...]:
    """ONLINE half: install the input rotation on exactly the fqns ``metadata`` records.

    Returns the fqns rotated, or ``()`` when ``metadata`` declares no rotation -- the plain
    artifacts, which have to be left exactly as they are. RAISES on any other outcome: an
    unusable contract, an fqn this model does not have, a target that is not a Linear, an
    ``in_features`` the recorded group does not divide, or a Linear already rotated. The prequant
    loader turns a raise into a refused checkpoint and a dense fallback.

    Call AFTER ``load_state_dict`` and BEFORE ``apply_small_m_padding``: after, because the meta
    retry path rebuilds the module from the config and would discard an earlier swap; before,
    because padding reparents the Linears under a wrapper while the recorded fqns name the
    unwrapped tree."""
    if not declares_rotation(metadata):
        return ()
    problem = rotation_metadata_error(metadata)
    if problem:
        raise ValueError(problem)

    from torch import nn

    group_size = int(metadata[ROTATION_GROUP_KEY])
    fqns = list(metadata[ROTATION_FQNS_KEY])
    modules = dict(transformer.named_modules())
    missing = [fqn for fqn in fqns if fqn not in modules]
    if missing:
        raise ValueError(
            f"activation rotation names {len(missing)} fqn(s) this model does not have "
            f"(e.g. {missing[0]!r}); the checkpoint and this build disagree about the model"
        )
    for fqn in fqns:
        module = modules[fqn]
        if not isinstance(module, nn.Linear):
            raise ValueError(f"activation rotation target {fqn!r} is not an nn.Linear")
        if is_rotated_linear(module):
            raise ValueError(f"activation rotation target {fqn!r} is already rotated")

View on GitHub (pinned to 203007d190)

Solutions

Rebuild/re-export the checkpoint with this build so the metadata records the implemented CONVROT_KIND
Or strip the rotation metadata and use a dense (unrotated) checkpoint
Keep builder and loader on the same code version when producing rotated checkpoints
Catch the refusal and fall back to the dense model path rather than retrying the load

Example fix

# before
# checkpoint metadata: {"rotation_kind": "learned_r"}
apply_activation_rotation(transformer, metadata)

# after
# rebuild with the shipped builder so metadata records:
# {"rotation_kind": "convrot", "rotation_group": 64, "rotation_fqns": [...]}
apply_activation_rotation(transformer, metadata)

Defensive patterns

Strategy: fallback

Validate before calling

from studio.backend.core.inference.diffusion_convrot import CONVROT_KIND, declares_rotation, rotation_metadata_error

def rotation_supported(metadata) -> bool:
    if not declares_rotation(metadata):
        return True
    return metadata.get(ROTATION_KIND_KEY) == CONVROT_KIND and not rotation_metadata_error(metadata)

Try / catch

try:
    apply_activation_rotation(transformer, metadata)
except ValueError as e:
    logger.warning("refusing rotated checkpoint (%s); falling back to dense", e)
    transformer = load_dense_checkpoint()  # the prequant loader's documented fallback

Prevention

Build and load rotated checkpoints with the same build version
Treat an unknown rotation kind as a hard refusal — never apply a scheme this build cannot undo
Keep a dense export alongside rotated ones for cross-version loads

When it happens

Trigger: Loading a checkpoint whose metadata records rotation kind != CONVROT_KIND (e.g. a future/other scheme like a learned rotation); the prequant loader's rotation_metadata_error surfaces it and apply_activation_rotation re-raises. The prequant loader turns the raise into a refused checkpoint and dense fallback.

Common situations: Checkpoint built by a newer or differently-configured build of the studio; hand-edited safetensors metadata; mixing checkpoints across versions after a rotation-scheme change.

Related errors

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