hiyouga/LlamaFactory · error · ValueError

`kt_cpu_activation` is only valid when `use_kt: true`.

Error message

`kt_cpu_activation` is only valid when `use_kt: true`.

What it means

Raised in the KTransformers arguments __post_init__ (model_args.py:533) when kt_cpu_activation is set but use_kt is false. The CPU activation policy only exists for KTransformers runs (experts on CPU), so configuring it without enabling KT is rejected to prevent a silently-ignored setting.

Source

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

            "kt_full_weight_grad",
            "kt_lora_alpha",
            "kt_lora_dropout",
            "kt_lora_expert_intermediate_size",
            "kt_lora_expert_num",
            "kt_lora_rank",
            "kt_non_expert_weight_path",
            "kt_skip_expert_loading",
            "kt_train_mode",
            "kt_use_lora_experts",
            "kt_weight_path",
        }
    )

    def __post_init__(self) -> None:
        if self.kt_cpu_activation not in {None, "retain", "recompute"}:
            raise ValueError("`kt_cpu_activation` must be `retain` or `recompute`.")
        if not self.use_kt and self.kt_cpu_activation is not None:
            raise ValueError("`kt_cpu_activation` is only valid when `use_kt: true`.")

    def get_kt_activation_policy(self) -> dict[str, str]:
        r"""Resolve LF's GPU checkpoint switch and KT's CPU activation setting."""
        gpu_activation = "retain" if self.disable_gradient_checkpointing else "recompute"
        cpu_activation = self.kt_cpu_activation or gpu_activation
        if cpu_activation == "recompute" and gpu_activation == "retain":
            raise ValueError(
                "`kt_cpu_activation: recompute` requires GPU gradient checkpointing. "
                "Set `disable_gradient_checkpointing: false` or use `kt_cpu_activation: retain`."
            )

        return {"cpu": cpu_activation, "gpu": gpu_activation}

    @staticmethod
    def _get_accelerator_kt_config(training_args: Any) -> Any:
        accelerator_config = getattr(training_args, "accelerator_config", None)
        if isinstance(accelerator_config, dict):
            return accelerator_config.get("kt_config")

View on GitHub (pinned to f28afaf635)

Solutions

1. Add use_kt: true to the same config
2. Or remove kt_cpu_activation (and ideally other kt_* keys) when running without KTransformers
3. Keep all kt_* settings under a single optional YAML include you only merge when use_kt is true

Example fix

# before
use_kt: false
kt_cpu_activation: retain

# after
use_kt: true
kt_cpu_activation: retain

if not cfg.get('use_kt'):
    cfg = {k: v for k, v in cfg.items() if not k.startswith('kt_')}  # strip stray KT keys

def kt_keys_consistent(cfg: dict) -> bool:
    kt_set = {k for k in cfg if k.startswith('kt_')}
    return cfg.get('use_kt') or not kt_set

When it happens

Trigger: A config with kt_cpu_activation: retain but no use_kt: true; toggling use_kt off for a comparison run while leaving other kt_* keys in place; partial migration from a KT example config.

Common situations: A/B testing KT vs HF execution by flipping only use_kt; YAML anchors that spread kt_* keys across experiments; stale keys left after abandoning KT.

Related errors

• `kt_cpu_activation` must be `retain` or `recompute`.
• LLaMA-Factory `kt_config` must be a flat mapping.
• `virtual_pipeline_model_parallel_size` must be >= 1 when set
• `sequence_parallel` requires `tensor_model_parallel_size` >
• `recompute_granularity` must be 'full' or 'selective'.

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