{"record":{"id":"ad65cdab29c4bebc","repo":"hiyouga/LlamaFactory","slug":"the-installed-kt-kernel-does-not-provide-the-activ","errorCode":null,"errorMessage":"The installed kt-kernel does not provide the activation checkpoint context API.","messagePattern":"The installed kt-kernel does not provide the activation checkpoint context API\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/model/model_utils/checkpointing.py","lineNumber":55,"sourceCode":"    from ...hparams import ModelArguments\n\n\nlogger = logging.get_logger(__name__)\n\n\ndef _get_gradient_checkpointing_kwargs(model_args: \"ModelArguments\") -> dict[str, Any]:\n    r\"\"\"Build checkpoint kwargs through KT's public activation-context provider.\"\"\"\n    if not model_args.use_kt:\n        return {\"use_reentrant\": model_args.use_reentrant_gc}\n\n    policy = model_args.get_kt_activation_policy()\n    if policy[\"gpu\"] != \"recompute\":\n        return {\"use_reentrant\": False}\n\n    try:\n        from kt_kernel.sft import get_activation_checkpoint_context_fn\n    except (ImportError, ModuleNotFoundError) as exc:\n        raise RuntimeError(\"The installed kt-kernel does not provide the activation checkpoint context API.\") from exc\n\n    return {\"use_reentrant\": False, \"context_fn\": get_activation_checkpoint_context_fn()}\n\n\ndef get_unsloth_gradient_checkpointing_func() -> Callable:\n    class UnslothGradientCheckpointing(torch.autograd.Function):\n        r\"\"\"Saves VRAM by smartly offloading to RAM.\"\"\"\n\n        @staticmethod\n        @torch.cuda.amp.custom_fwd\n        def forward(\n            ctx: \"torch.autograd.Function\",\n            forward_function: \"torch.Module\",\n            hidden_states: \"torch.Tensor\",\n            *args: Union[\"torch.Tensor\", Any],\n        ) -> \"torch.Tensor\":\n            saved_hidden_states = hidden_states.to(\"cpu\", non_blocking=True)\n            with torch.no_grad():","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/model/model_utils/checkpointing.py#L37-L73","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Upgrade kt-kernel to the version matching your LlamaFactory release (check the project's requirements/pyproject pin).","Verify the API exists: python -c \"from kt_kernel.sft import get_activation_checkpoint_context_fn\".","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.","If the policy does not need GPU recompute, adjust the KT activation policy so policy['gpu'] != 'recompute' to bypass the import."],"exampleFix":"# before (yaml)\nenable_thu_kt: true\n\n# after (env fix)\npip install -U kt-kernel  # or the pinned version from LlamaFactory's requirements\n# verify:\n# python -c \"from kt_kernel.sft import get_activation_checkpoint_context_fn\"","handlingStrategy":"validation","validationCode":"def kt_checkpoint_api_available() -> bool:\n    try:\n        from kt_kernel.sft import get_activation_checkpoint_context_fn  # noqa: F401\n        return True\n    except (ImportError, ModuleNotFoundError):\n        return False\n\nassert kt_checkpoint_api_available(), \"upgrade kt-kernel or disable use_kt\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin kt-kernel to the version paired with your LlamaFactory release.","Add an env smoke test that imports kt_kernel.sft.get_activation_checkpoint_context_fn before long runs."],"tags":["kt-kernel","dependency","gradient-checkpointing","environment"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}