hiyouga/LlamaFactory · error · TypeError

LLaMA-Factory `kt_config` must be a flat mapping.

Error message

LLaMA-Factory `kt_config` must be a flat mapping.

What it means

Raised by _normalize_advanced_kt_config (model_args.py:558) as a TypeError when the kt_config advanced setting is present but is not a dict. Unlike most YAML fields, kt_config must be a flat mapping of arbitrary KTransformers keys to values; a string, list, or scalar is rejected because it is passed through to KTransformers as a mapping.

Source

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

            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")
        return getattr(accelerator_config, "kt_config", None)

    def _normalize_advanced_kt_config(self, raw_config: Any) -> dict[str, Any]:
        if raw_config is None:
            return {}
        if not isinstance(raw_config, dict):
            raise TypeError("LLaMA-Factory `kt_config` must be a flat mapping.")

        config = dict(raw_config)
        conflicts = sorted(set(config) & self._KT_DERIVED_KEYS)
        if conflicts:
            raise ValueError(f"These `kt_config` values are derived from LLaMA-Factory arguments: {conflicts}.")
        return config

    def _get_advanced_kt_config(self, training_args: Any) -> dict[str, Any]:
        raw_config = getattr(training_args, "kt_config", None)
        accelerator_config = self._get_accelerator_kt_config(training_args)
        if raw_config is None:
            if accelerator_config is not None:
                raise ValueError(
                    "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:

View on GitHub (pinned to f28afaf635)

Solutions

1. Write kt_config as a YAML mapping: kt_config: {key: value} or indented key/value lines
2. Do not quote the whole mapping (quoting turns it into a string)
3. Remove kt_config if you have no advanced KTransformers overrides — all necessary basics come from the kt_* arguments

Example fix

# before
kt_config: "{"gen_config": {"temperature": 0.7}}"   # a quoted string

# after
kt_config:
  gen_config:
    temperature: 0.7

ktc = cfg.get('kt_config')
assert ktc is None or isinstance(ktc, dict), 'kt_config must be a YAML mapping, not a string/list'

def is_flat_mapping(v: object) -> bool:
    return v is None or isinstance(v, dict)

try:
    policy = model_args._get_advanced_kt_config(training_args)
except TypeError as e:
    if 'flat mapping' in str(e):
        cfg['kt_config'] = yaml.safe_load(cfg['kt_config'])  # repair string->dict
    else:
        raise

When it happens

Trigger: Writing kt_config: "path/to/config.yaml" (file paths are not supported for this field); kt_config: [a, b]; kt_config: true. Note this is a TypeError, not ValueError, because the type itself is wrong.

Common situations: Users assuming every LlamaFactory string config accepts a file path (contrast extra_config in the Megatron bridge which does); pasting the KTransformers project's nested config file directly under kt_config; quoting a mapping so YAML yields a string.

Related errors

• YAML config must be a dictionary mapping tokens to descripti
• `kt_cpu_activation` must be `retain` or `recompute`.
• `kt_cpu_activation` is only valid when `use_kt: true`.
• Please specify dataset for training.
• `virtual_pipeline_model_parallel_size` must be >= 1 when set

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