{"record":{"id":"b408cba55c16b446","repo":"hiyouga/LlamaFactory","slug":"llama-factory-kt-config-must-be-a-flat-mapping","errorCode":null,"errorMessage":"LLaMA-Factory `kt_config` must be a flat mapping.","messagePattern":"LLaMA-Factory `kt_config` must be a flat mapping\\.","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/hparams/model_args.py","lineNumber":558,"sourceCode":"            raise ValueError(\n                \"`kt_cpu_activation: recompute` requires GPU gradient checkpointing. \"\n                \"Set `disable_gradient_checkpointing: false` or use `kt_cpu_activation: retain`.\"\n            )\n\n        return {\"cpu\": cpu_activation, \"gpu\": gpu_activation}\n\n    @staticmethod\n    def _get_accelerator_kt_config(training_args: Any) -> Any:\n        accelerator_config = getattr(training_args, \"accelerator_config\", None)\n        if isinstance(accelerator_config, dict):\n            return accelerator_config.get(\"kt_config\")\n        return getattr(accelerator_config, \"kt_config\", None)\n\n    def _normalize_advanced_kt_config(self, raw_config: Any) -> dict[str, Any]:\n        if raw_config is None:\n            return {}\n        if not isinstance(raw_config, dict):\n            raise TypeError(\"LLaMA-Factory `kt_config` must be a flat mapping.\")\n\n        config = dict(raw_config)\n        conflicts = sorted(set(config) & self._KT_DERIVED_KEYS)\n        if conflicts:\n            raise ValueError(f\"These `kt_config` values are derived from LLaMA-Factory arguments: {conflicts}.\")\n        return config\n\n    def _get_advanced_kt_config(self, training_args: Any) -> dict[str, Any]:\n        raw_config = getattr(training_args, \"kt_config\", None)\n        accelerator_config = self._get_accelerator_kt_config(training_args)\n        if raw_config is None:\n            if accelerator_config is not None:\n                raise ValueError(\n                    \"Put KTransformers settings in the LLaMA-Factory training YAML `kt_config`; \"\n                    \"remove `kt_config` from the Accelerate config.\"\n                )\n            return {}\n        if accelerator_config is not None and accelerator_config != raw_config:","sourceCodeStart":540,"sourceCodeEnd":576,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/hparams/model_args.py#L540-L576","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Write kt_config as a YAML mapping: kt_config: {key: value} or indented key/value lines","Do not quote the whole mapping (quoting turns it into a string)","Remove kt_config if you have no advanced KTransformers overrides — all necessary basics come from the kt_* arguments"],"exampleFix":"# before\nkt_config: \"{\"gen_config\": {\"temperature\": 0.7}}\"   # a quoted string\n\n# after\nkt_config:\n  gen_config:\n    temperature: 0.7","handlingStrategy":"type-guard","validationCode":"ktc = cfg.get('kt_config')\nassert ktc is None or isinstance(ktc, dict), 'kt_config must be a YAML mapping, not a string/list'","typeGuard":"def is_flat_mapping(v: object) -> bool:\n    return v is None or isinstance(v, dict)","tryCatchPattern":"try:\n    policy = model_args._get_advanced_kt_config(training_args)\nexcept TypeError as e:\n    if 'flat mapping' in str(e):\n        cfg['kt_config'] = yaml.safe_load(cfg['kt_config'])  # repair string->dict\n    else:\n        raise","preventionTips":["Never quote the kt_config mapping in YAML","kt_config takes inline mappings only; there is no file-path form"],"tags":["ktransformers","yaml","type-error","config-validation"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}