hiyouga/LlamaFactory · error · ValueError

KTransformers supplies its checkpoint context; remove `gradi

Error message

KTransformers supplies its checkpoint context; remove `gradient_checkpointing_kwargs`.

What it means

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.

Source

Thrown at src/llamafactory/hparams/model_args.py:590

                    "Put KTransformers settings in the LLaMA-Factory training YAML `kt_config`; "
                    "remove `kt_config` from the Accelerate config."
                )
            return {}
        if accelerator_config is not None and accelerator_config != raw_config:
            raise ValueError("LLaMA-Factory YAML and Accelerate config cannot define different KT settings.")
        return self._normalize_advanced_kt_config(raw_config)

    def configure_kt_checkpointing(self, training_args: Any) -> None:
        r"""Keep LLaMA-Factory as the single gradient-checkpointing entry point."""
        if self.use_unsloth or self.use_unsloth_gc:
            raise ValueError("KTransformers cannot be combined with Unsloth checkpoint wrapping.")
        if getattr(training_args, "gradient_checkpointing", False):
            raise ValueError(
                "KTransformers uses LLaMA-Factory's `disable_gradient_checkpointing`; "
                "remove `gradient_checkpointing: true`."
            )
        if getattr(training_args, "gradient_checkpointing_kwargs", None) is not None:
            raise ValueError("KTransformers supplies its checkpoint context; remove `gradient_checkpointing_kwargs`.")

        fsdp_config = getattr(training_args, "fsdp_config", None)
        if isinstance(fsdp_config, dict) and fsdp_config.get("activation_checkpointing"):
            raise ValueError("Disable FSDP activation checkpointing when using KTransformers.")
        if os.environ.get("FSDP_ACTIVATION_CHECKPOINTING", "false").lower() in {"1", "true", "yes"}:
            raise ValueError("Disable FSDP activation checkpointing when using KTransformers.")

        self.get_kt_activation_policy()
        if not self.disable_gradient_checkpointing:
            self.use_reentrant_gc = False
        training_args.gradient_checkpointing = False
        training_args.gradient_checkpointing_kwargs = None

    def get_kt_config_dict(
        self,
        finetuning_args: Any,
        model_max_length: int | None,
        advanced_config: dict[str, Any] | None = None,

View on GitHub (pinned to f28afaf635)

Solutions

1. Delete the `gradient_checkpointing_kwargs` key from the YAML / CLI when using KTransformers.
2. If you needed non-reentrant checkpointing, rely on KT's default (it forces use_reentrant_gc = False unless checkpointing is disabled).

Example fix

# before (yaml)
use_kt: true
gradient_checkpointing_kwargs:
  use_reentrant: true

# after (yaml)
use_kt: true

if cfg.get('use_kt') and cfg.get('gradient_checkpointing_kwargs') is not None:
    raise SystemExit('KT supplies checkpoint kwargs itself; remove gradient_checkpointing_kwargs')

When it happens

Trigger: 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.

Common situations: Configs migrated from multi-GPU or reentrant-checkpointing setups that pin gradient_checkpointing_kwargs for older Transformers versions, then reused for a KT run.

Related errors

• KTransformers uses LLaMA-Factory's `disable_gradient_checkpo
• Disable FSDP activation checkpointing when using KTransforme
• KTransformers thin integration currently supports LoRA finet
• `kt_model_max_length` must be a positive integer.
• `kt_config` requires `use_kt: true`.

AI-assisted analysis of hiyouga/LlamaFactory@f28afaf635 (2026-08-14). Data as JSON: /api/errors/9ee78226dd23f627. Report an issue: GitHub.