hiyouga/LlamaFactory · error · ValueError

`kt_cpu_activation` must be `retain` or `recompute`.

Error message

`kt_cpu_activation` must be `retain` or `recompute`.

What it means

Raised in the KTransformers arguments __post_init__ (model_args.py:531) when kt_cpu_activation is set to a value outside {None, 'retain', 'recompute'}. This switch decides whether CPU-side (MoE expert) activations are kept in memory ('retain') or recomputed on backward ('recompute'); only those two strings plus unset are accepted, case-sensitively.

Source

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

            "kt_activation_policy",
            "kt_expert_checkpoint_path",
            "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)

View on GitHub (pinned to f28afaf635)

Solutions

1. Use exactly 'retain' or 'recompute', or omit the key
2. Remember the default follows the GPU gradient-checkpointing setting (see get_kt_activation_policy), so omission is usually fine
3. Fix casing/typos

Example fix

# before
kt_cpu_activation: Retain

# after
kt_cpu_activation: retain

if cfg.get('kt_cpu_activation') not in (None, 'retain', 'recompute'):
    raise SystemExit('kt_cpu_activation must be retain|recompute or omitted')

def is_kt_policy(v: str | None) -> bool:
    return v in (None, 'retain', 'recompute')

When it happens

Trigger: kt_cpu_activation: Retain, 'off', 'auto', or 'both'; passing a boolean; copying a value from the KTransformers project's own config vocabulary that does not map onto this enum.

Common situations: Config written by hand or by an LLM guessing values; porting KTransformers YAML where the corresponding knob has a different name/values; casing differences from documentation.

Related errors

• `kt_cpu_activation` is only valid when `use_kt: true`.
• 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/59ef0484ae24fedc. Report an issue: GitHub.