{"record":{"id":"59ef0484ae24fedc","repo":"hiyouga/LlamaFactory","slug":"kt-cpu-activation-must-be-retain-or-recompute","errorCode":null,"errorMessage":"`kt_cpu_activation` must be `retain` or `recompute`.","messagePattern":"`kt_cpu_activation` must be `retain` or `recompute`\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/hparams/model_args.py","lineNumber":531,"sourceCode":"            \"kt_activation_policy\",\n            \"kt_expert_checkpoint_path\",\n            \"kt_full_weight_grad\",\n            \"kt_lora_alpha\",\n            \"kt_lora_dropout\",\n            \"kt_lora_expert_intermediate_size\",\n            \"kt_lora_expert_num\",\n            \"kt_lora_rank\",\n            \"kt_non_expert_weight_path\",\n            \"kt_skip_expert_loading\",\n            \"kt_train_mode\",\n            \"kt_use_lora_experts\",\n            \"kt_weight_path\",\n        }\n    )\n\n    def __post_init__(self) -> None:\n        if self.kt_cpu_activation not in {None, \"retain\", \"recompute\"}:\n            raise ValueError(\"`kt_cpu_activation` must be `retain` or `recompute`.\")\n        if not self.use_kt and self.kt_cpu_activation is not None:\n            raise ValueError(\"`kt_cpu_activation` is only valid when `use_kt: true`.\")\n\n    def get_kt_activation_policy(self) -> dict[str, str]:\n        r\"\"\"Resolve LF's GPU checkpoint switch and KT's CPU activation setting.\"\"\"\n        gpu_activation = \"retain\" if self.disable_gradient_checkpointing else \"recompute\"\n        cpu_activation = self.kt_cpu_activation or gpu_activation\n        if cpu_activation == \"recompute\" and gpu_activation == \"retain\":\n            raise ValueError(\n                \"`kt_cpu_activation: recompute` requires GPU gradient checkpointing. \"\n                \"Set `disable_gradient_checkpointing: false` or use `kt_cpu_activation: retain`.\"\n            )\n\n        return {\"cpu\": cpu_activation, \"gpu\": gpu_activation}\n\n    @staticmethod\n    def _get_accelerator_kt_config(training_args: Any) -> Any:\n        accelerator_config = getattr(training_args, \"accelerator_config\", None)","sourceCodeStart":513,"sourceCodeEnd":549,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/hparams/model_args.py#L513-L549","documentation":"Raised in the KTransformers arguments __post_init__ (model_args.py:531) when kt_cpu_activation is set to a value outside {None, 'retain', 'recompute'}. This switch decides whether CPU-side (MoE expert) activations are kept in memory ('retain') or recomputed on backward ('recompute'); only those two strings plus unset are accepted, case-sensitively.","triggerScenarios":"kt_cpu_activation: Retain, 'off', 'auto', or 'both'; passing a boolean; copying a value from the KTransformers project's own config vocabulary that does not map onto this enum.","commonSituations":"Config written by hand or by an LLM guessing values; porting KTransformers YAML where the corresponding knob has a different name/values; casing differences from documentation.","solutions":["Use exactly 'retain' or 'recompute', or omit the key","Remember the default follows the GPU gradient-checkpointing setting (see get_kt_activation_policy), so omission is usually fine","Fix casing/typos"],"exampleFix":"# before\nkt_cpu_activation: Retain\n\n# after\nkt_cpu_activation: retain","handlingStrategy":"type-guard","validationCode":"if cfg.get('kt_cpu_activation') not in (None, 'retain', 'recompute'):\n    raise SystemExit('kt_cpu_activation must be retain|recompute or omitted')","typeGuard":"def is_kt_policy(v: str | None) -> bool:\n    return v in (None, 'retain', 'recompute')","tryCatchPattern":null,"preventionTips":["Omit kt_cpu_activation unless you specifically need CPU/GPU policies to differ","Copy exact strings from the field's help text"],"tags":["ktransformers","cpu-offload","config-validation"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}