{"record":{"id":"9ee78226dd23f627","repo":"hiyouga/LlamaFactory","slug":"ktransformers-supplies-its-checkpoint-context-rem","errorCode":null,"errorMessage":"KTransformers supplies its checkpoint context; remove `gradient_checkpointing_kwargs`.","messagePattern":"KTransformers supplies its checkpoint context; remove `gradient_checkpointing_kwargs`\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/hparams/model_args.py","lineNumber":590,"sourceCode":"                    \"Put KTransformers settings in the LLaMA-Factory training YAML `kt_config`; \"\n                    \"remove `kt_config` from the Accelerate config.\"\n                )\n            return {}\n        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,","sourceCodeStart":572,"sourceCodeEnd":608,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/hparams/model_args.py#L572-L608","documentation":"Raised by configure_kt_checkpointing when use_kt is enabled and gradient_checkpointing_kwargs is not None. KTransformers installs its own checkpoint context (use_reentrant_gc handling is done internally), so user-supplied kwargs like use_reentrant: true would conflict and are rejected.","triggerScenarios":"A training YAML with use_kt: true plus a gradient_checkpointing_kwargs block (e.g. {use_reentrant: true}), or the equivalent --gradient_checkpointing_kwargs CLI argument.","commonSituations":"Configs migrated from multi-GPU or reentrant-checkpointing setups that pin gradient_checkpointing_kwargs for older Transformers versions, then reused for a KT run.","solutions":["Delete the `gradient_checkpointing_kwargs` key from the YAML / CLI when using KTransformers.","If you needed non-reentrant checkpointing, rely on KT's default (it forces use_reentrant_gc = False unless checkpointing is disabled)."],"exampleFix":"# before (yaml)\nuse_kt: true\ngradient_checkpointing_kwargs:\n  use_reentrant: true\n\n# after (yaml)\nuse_kt: true","handlingStrategy":"validation","validationCode":"if cfg.get('use_kt') and cfg.get('gradient_checkpointing_kwargs') is not None:\n    raise SystemExit('KT supplies checkpoint kwargs itself; remove gradient_checkpointing_kwargs')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Audit YAMLs for checkpoint-related keys before flipping use_kt to true."],"tags":["ktransformers","gradient-checkpointing","config","llamafactory"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}