hiyouga/LlamaFactory · error · ValueError

`kt_model_max_length` must be a positive integer.

Error message

`kt_model_max_length` must be a positive integer.

What it means

Raised by get_kt_config_dict when the user-supplied kt_config.kt_model_max_length cannot be converted to int (TypeError/ValueError, e.g. a string like 'long' or a nested dict). kt_model_max_length is the token-capacity hint KT uses to size CPU expert buffers, so it must be a clean positive integer.

Source

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

        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,
    ) -> dict[str, Any]:
        r"""Map LLaMA-Factory-owned training values to the public KT configuration."""
        if getattr(finetuning_args, "finetuning_type", None) != "lora":
            raise ValueError("KTransformers thin integration currently supports LoRA finetuning only.")

        kt_config = dict(advanced_config or {})
        configured_capacity = kt_config.pop("kt_model_max_length", None)
        if configured_capacity is not None:
            try:
                configured_capacity = int(configured_capacity)
            except (TypeError, ValueError) as exc:
                raise ValueError("`kt_model_max_length` must be a positive integer.") from exc
            if configured_capacity <= 0:
                raise ValueError("`kt_model_max_length` must be a positive integer.")

        kt_config.update(
            {
                "kt_lora_rank": getattr(finetuning_args, "lora_rank", None),
                "kt_lora_alpha": getattr(finetuning_args, "lora_alpha", None),
                "kt_lora_dropout": getattr(finetuning_args, "lora_dropout", None),
                "kt_weight_path": self.kt_weight_path,
                "kt_non_expert_weight_path": self.kt_non_expert_weight_path,
                "kt_expert_checkpoint_path": self.kt_expert_checkpoint_path,
                "kt_model_max_length": max(model_max_length or 0, configured_capacity or 0) or None,
                "kt_use_lora_experts": self.kt_use_lora_experts,
                "kt_lora_expert_num": self.kt_lora_expert_num,
                "kt_lora_expert_intermediate_size": self.kt_lora_expert_intermediate_size,
                "kt_activation_policy": self.get_kt_activation_policy(),
                "kt_train_mode": "lora",
                "kt_full_weight_grad": False,

View on GitHub (pinned to f28afaf635)

Solutions

1. Set `kt_model_max_length` to a plain positive integer, e.g. 8192, inside `kt_config`.
2. Remove the key entirely to let LLaMA-Factory derive capacity from `cutoff_len` and batch size.

Example fix

# before (yaml)
kt_config:
  kt_model_max_length: 8k

# after (yaml)
kt_config:
  kt_model_max_length: 8192

v = (cfg.get('kt_config') or {}).get('kt_model_max_length')
if v is not None and (not isinstance(v, int) or isinstance(v, bool) or v <= 0):
    raise SystemExit('kt_model_max_length must be a positive integer')

When it happens

Trigger: Passing kt_config: {kt_model_max_length: abc} or a float-string/non-numeric value in the YAML; int() conversion inside the try block raises and is re-raised as this ValueError.

Common situations: YAML typos, unquoted placeholder values, or copy-pasting 'kt_model_max_length: 8k'-style shorthand from notes into the config.

Related errors

• KTransformers uses LLaMA-Factory's `disable_gradient_checkpo
• KTransformers supplies its checkpoint context; remove `gradi
• Disable FSDP activation checkpointing when using KTransforme
• KTransformers thin integration currently supports LoRA finet
• `kt_config` requires `use_kt: true`.

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