{"record":{"id":"2502ae299339266c","repo":"hiyouga/LlamaFactory","slug":"ktransformers-operation-requires-a-local-adapter","errorCode":null,"errorMessage":"KTransformers {operation} requires a local adapter directory.","messagePattern":"KTransformers (.+?) requires a local adapter directory\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/hparams/model_args.py","lineNumber":656,"sourceCode":"                \"kt_full_weight_grad\": False,\n            }\n        )\n        return {key: value for key, value in kt_config.items() if value is not None}\n\n    def _resolve_kt_adapter_artifact_dir(self, operation: str) -> str | None:\n        if not self.adapter_name_or_path:\n            return None\n        if len(self.adapter_name_or_path) != 1:\n            raise ValueError(\"KTransformers accepts a single `adapter_name_or_path`.\")\n\n        adapter_root = os.path.realpath(os.path.expanduser(self.adapter_name_or_path[0]))\n        adapter_dir = adapter_root\n        if self.adapter_folder:\n            adapter_dir = os.path.realpath(os.path.join(adapter_root, self.adapter_folder))\n            if os.path.commonpath((adapter_root, adapter_dir)) != adapter_root:\n                raise ValueError(\"`adapter_folder` must stay inside the KT adapter directory.\")\n        if not os.path.isdir(adapter_dir):\n            raise ValueError(f\"KTransformers {operation} requires a local adapter directory.\")\n        return adapter_dir\n\n    def apply_kt_config(self, finetuning_args: Any, training_args: Any, model_max_length: int | None) -> None:\n        r\"\"\"Apply LLaMA-Factory KT args to transformers/accelerate KT integration points.\"\"\"\n        if not self.use_kt:\n            return\n\n        self.configure_kt_checkpointing(training_args)\n        kt_config = self.get_kt_config_dict(\n            finetuning_args,\n            model_max_length,\n            self._get_advanced_kt_config(training_args),\n        )\n        update_kt_config = getattr(training_args, \"update_kt_config\", None)\n        if not callable(update_kt_config):\n            raise RuntimeError(\n                \"The installed Transformers-KT does not provide `TrainingArguments.update_kt_config()`.\"\n            )","sourceCodeStart":638,"sourceCodeEnd":674,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/hparams/model_args.py#L638-L674","documentation":"Raised by _resolve_kt_adapter_artifact_dir when the resolved adapter directory does not exist on the local filesystem. KT training/inference reads the LoRA artifacts directly from disk, so remote repo IDs or missing paths cannot be lazy-downloaded the way vanilla LLaMA-Factory adapters can.","triggerScenarios":"adapter_name_or_path points to a nonexistent local dir, a bare HF hub repo id, or the dir was moved/deleted after training; operation is 'training' via apply_kt_config or 'inference' via configure_kt_loading, and the message names it.","commonSituations":"Resuming an old run after cleaning saves/, or copy-pasting an adapter path valid on another machine.","solutions":["Check the path exists: `ls <adapter_name_or_path>` and fix typos / restore the directory.","Download or copy the adapter to local disk first if it lives on the HF Hub.","If the adapter is gone, retrain or re-export before the KT run."],"exampleFix":"# before (yaml)\nuse_kt: true\nadapter_name_or_path: saves/lora_v2/checkpoint-500\n  # dir deleted\n\n# after (bash)\nls saves/lora_v2/  # pick an existing checkpoint\n# after (yaml)\nuse_kt: true\nadapter_name_or_path: saves/lora_v2/checkpoint-496","handlingStrategy":"validation","validationCode":"import os\np = cfg.get('adapter_name_or_path')\nif p and not os.path.isdir(os.path.expanduser(p[0] if isinstance(p, list) else p)):\n    raise SystemExit(f'adapter dir not found: {p}')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin adapter paths with absolute paths in shared cluster configs.","Verify artifact existence in a preflight step of job scripts."],"tags":["ktransformers","adapter","filesystem","llamafactory"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}