hiyouga/LlamaFactory · error · RuntimeError

The installed kt-kernel does not provide the activation chec

Error message

The installed kt-kernel does not provide the activation checkpoint context API.

What it means

When use_kt is enabled and the KT activation policy requires GPU recompute, LlamaFactory tries to import get_activation_checkpoint_context_fn from kt_kernel.sft to build gradient-checkpointing kwargs. If the installed kt-kernel package is missing or too old to expose that public API, the ImportError is re-raised as a RuntimeError with a clear message. It is an environment/version problem, not a config-logic problem.

Source

Thrown at src/llamafactory/model/model_utils/checkpointing.py:55

    from ...hparams import ModelArguments


logger = logging.get_logger(__name__)


def _get_gradient_checkpointing_kwargs(model_args: "ModelArguments") -> dict[str, Any]:
    r"""Build checkpoint kwargs through KT's public activation-context provider."""
    if not model_args.use_kt:
        return {"use_reentrant": model_args.use_reentrant_gc}

    policy = model_args.get_kt_activation_policy()
    if policy["gpu"] != "recompute":
        return {"use_reentrant": False}

    try:
        from kt_kernel.sft import get_activation_checkpoint_context_fn
    except (ImportError, ModuleNotFoundError) as exc:
        raise RuntimeError("The installed kt-kernel does not provide the activation checkpoint context API.") from exc

    return {"use_reentrant": False, "context_fn": get_activation_checkpoint_context_fn()}


def get_unsloth_gradient_checkpointing_func() -> Callable:
    class UnslothGradientCheckpointing(torch.autograd.Function):
        r"""Saves VRAM by smartly offloading to RAM."""

        @staticmethod
        @torch.cuda.amp.custom_fwd
        def forward(
            ctx: "torch.autograd.Function",
            forward_function: "torch.Module",
            hidden_states: "torch.Tensor",
            *args: Union["torch.Tensor", Any],
        ) -> "torch.Tensor":
            saved_hidden_states = hidden_states.to("cpu", non_blocking=True)
            with torch.no_grad():

View on GitHub (pinned to f28afaf635)

Solutions

1. Upgrade kt-kernel to the version matching your LlamaFactory release (check the project's requirements/pyproject pin).
2. Verify the API exists: python -c "from kt_kernel.sft import get_activation_checkpoint_context_fn".
3. If you did not intend to use KT, set enable_thu_kt/use_kt to false so the code path returns plain use_reentrant kwargs.
4. If the policy does not need GPU recompute, adjust the KT activation policy so policy['gpu'] != 'recompute' to bypass the import.

Example fix

# before (yaml)
enable_thu_kt: true

# after (env fix)
pip install -U kt-kernel  # or the pinned version from LlamaFactory's requirements
# verify:
# python -c "from kt_kernel.sft import get_activation_checkpoint_context_fn"

def kt_checkpoint_api_available() -> bool:
    try:
        from kt_kernel.sft import get_activation_checkpoint_context_fn  # noqa: F401
        return True
    except (ImportError, ModuleNotFoundError):
        return False

assert kt_checkpoint_api_available(), "upgrade kt-kernel or disable use_kt"

When it happens

Trigger: ModelArguments with enable_thu_kt/use_kt=true and a KT activation policy whose 'gpu' entry equals 'recompute', while the installed kt_kernel package does not define get_activation_checkpoint_context_fn in kt_kernel.sft (wrong build, older version, or stub install).

Common situations: Upgrading LlamaFactory to a version that expects a newer kt-kernel API without upgrading kt-kernel; installing a CPU/compat wheel of kt-kernel that lacks the SFT kernels; partial installs where kt_kernel exists but the .sft submodule is absent.

Related errors

• megatron-bridge is required when USE_MEGATRON_BRIDGE=1. Plea
• mcore_adapter is required when USE_MCA=1. Please install `mc
• Qwen2VL requires 3D position ids for mrope.
• All 'dcp_path', 'hf_path', and 'config_path' are required.
• Both 'hf_path' and 'dcp_path' are required.

AI-assisted analysis of hiyouga/LlamaFactory@f28afaf635 (2026-08-14). Data as JSON: /api/errors/ad65cdab29c4bebc. Report an issue: GitHub.