{"record":{"id":"ba3a71e0a808bee9","repo":"hiyouga/LlamaFactory","slug":"ktransformers-uses-llama-factory-s-disable-gradie","errorCode":null,"errorMessage":"KTransformers uses LLaMA-Factory's `disable_gradient_checkpointing`; remove `gradient_checkpointing: true`.","messagePattern":"KTransformers uses LLaMA-Factory's `disable_gradient_checkpointing`; remove `gradient_checkpointing: true`\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/hparams/model_args.py","lineNumber":585,"sourceCode":"        raw_config = getattr(training_args, \"kt_config\", None)\n        accelerator_config = self._get_accelerator_kt_config(training_args)\n        if raw_config is None:\n            if accelerator_config is not None:\n                raise ValueError(\n                    \"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","sourceCodeStart":567,"sourceCodeEnd":603,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/hparams/model_args.py#L567-L603","documentation":"Raised by KTransformersArguments.configure_kt_checkpointing when use_kt is enabled and training_args.gradient_checkpointing is truthy. KTransformers manages its own checkpointing context and treats LLaMA-Factory's disable_gradient_checkpointing flag as the single control knob, so any explicit gradient_checkpointing: true in the config is rejected to avoid two checkpoint owners.","triggerScenarios":"Running llamafactory-cli train with use_kt: true plus gradient_checkpointing: true in the same YAML, or passing --gradient_checkpointing on the CLI; apply_kt_config -> configure_kt_checkpointing checks the flag before KT setup.","commonSituations":"Users copy a standard LLaMA-Factory LoRA SFT config (which commonly sets gradient_checkpointing: true to save VRAM) and add use_kt: true on top; the copied flag then aborts startup.","solutions":["Remove `gradient_checkpointing: true` from the training YAML / CLI args when `use_kt: true` is set.","Control checkpointing only through `disable_gradient_checkpointing` (false = KT recompute on, true = retain).","Re-run training after confirming no other config layer (Accelerate YAML, CLI overrides) re-adds the flag."],"exampleFix":"# before (yaml)\ncutoff_len: 4096\nuse_kt: true\ngradient_checkpointing: true\n\n# after (yaml)\ncutoff_len: 4096\nuse_kt: true\ndisable_gradient_checkpointing: false","handlingStrategy":"validation","validationCode":"# before launching\nif cfg.get('use_kt') and cfg.get('gradient_checkpointing'):\n    raise SystemExit('remove gradient_checkpointing for KT runs')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep one KT base YAML and layer model/data overrides instead of copying full examples.","Treat disable_gradient_checkpointing as the only checkpoint switch when use_kt is 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"}