{"record":{"id":"8c492bf850e91445","repo":"hiyouga/LlamaFactory","slug":"disable-fsdp-activation-checkpointing-when-using-k","errorCode":null,"errorMessage":"Disable FSDP activation checkpointing when using KTransformers.","messagePattern":"Disable FSDP activation checkpointing when using KTransformers\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/hparams/model_args.py","lineNumber":594,"sourceCode":"        if accelerator_config is not None and accelerator_config != raw_config:\n            raise ValueError(\"LLaMA-Factory YAML and Accelerate config cannot define different KT settings.\")\n        return self._normalize_advanced_kt_config(raw_config)\n\n    def configure_kt_checkpointing(self, training_args: Any) -> None:\n        r\"\"\"Keep LLaMA-Factory as the single gradient-checkpointing entry point.\"\"\"\n        if self.use_unsloth or self.use_unsloth_gc:\n            raise ValueError(\"KTransformers cannot be combined with Unsloth checkpoint wrapping.\")\n        if getattr(training_args, \"gradient_checkpointing\", False):\n            raise ValueError(\n                \"KTransformers uses LLaMA-Factory's `disable_gradient_checkpointing`; \"\n                \"remove `gradient_checkpointing: true`.\"\n            )\n        if getattr(training_args, \"gradient_checkpointing_kwargs\", None) is not None:\n            raise ValueError(\"KTransformers supplies its checkpoint context; remove `gradient_checkpointing_kwargs`.\")\n\n        fsdp_config = getattr(training_args, \"fsdp_config\", None)\n        if isinstance(fsdp_config, dict) and fsdp_config.get(\"activation_checkpointing\"):\n            raise ValueError(\"Disable FSDP activation checkpointing when using KTransformers.\")\n        if os.environ.get(\"FSDP_ACTIVATION_CHECKPOINTING\", \"false\").lower() in {\"1\", \"true\", \"yes\"}:\n            raise ValueError(\"Disable FSDP activation checkpointing when using KTransformers.\")\n\n        self.get_kt_activation_policy()\n        if not self.disable_gradient_checkpointing:\n            self.use_reentrant_gc = False\n        training_args.gradient_checkpointing = False\n        training_args.gradient_checkpointing_kwargs = None\n\n    def get_kt_config_dict(\n        self,\n        finetuning_args: Any,\n        model_max_length: int | None,\n        advanced_config: dict[str, Any] | None = None,\n    ) -> dict[str, Any]:\n        r\"\"\"Map LLaMA-Factory-owned training values to the public KT configuration.\"\"\"\n        if getattr(finetuning_args, \"finetuning_type\", None) != \"lora\":\n            raise ValueError(\"KTransformers thin integration currently supports LoRA finetuning only.\")","sourceCodeStart":576,"sourceCodeEnd":612,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/hparams/model_args.py#L576-L612","documentation":"Raised by configure_kt_checkpointing when training_args.fsdp_config is a dict whose activation_checkpointing entry is truthy. KTransformers provides its own activation policy (cpu/gpu retain vs recompute) and cannot share activation checkpointing duty with FSDP's wrapper-level scheme.","triggerScenarios":"Launching KT training with an fsdp_config YAML section containing activation_checkpointing: true (typical of FSDP full-sharding configs) while use_kt: true.","commonSituations":"Users on multi-node FSDP templates enable activation checkpointing to fit large MoE models, then switch to the KT AMX backend without pruning the fsdp_config block.","solutions":["Set `activation_checkpointing: false` or remove the key from `fsdp_config` in the training YAML.","Use LLaMA-Factory's `disable_gradient_checkpointing` / `kt_cpu_activation` to control KT activation memory instead."],"exampleFix":"# before (yaml)\nfsdp_config:\n  fsdp_offload_params: true\n  activation_checkpointing: true\nuse_kt: true\n\n# after (yaml)\nfsdp_config:\n  fsdp_offload_params: true\nuse_kt: true","handlingStrategy":"validation","validationCode":"fsdp = cfg.get('fsdp_config') or {}\nif cfg.get('use_kt') and isinstance(fsdp, dict) and fsdp.get('activation_checkpointing'):\n    raise SystemExit('disable fsdp activation_checkpointing for KT')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Strip FSDP tuning keys that duplicate KT memory-management responsibilities."],"tags":["ktransformers","fsdp","config","llamafactory"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}