{"record":{"id":"cb415f7da3c7ad5b","repo":"hiyouga/LlamaFactory","slug":"adapter-folder-must-stay-inside-the-kt-adapter-d","errorCode":null,"errorMessage":"`adapter_folder` must stay inside the KT adapter directory.","messagePattern":"`adapter_folder` must stay inside the KT adapter directory\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/hparams/model_args.py","lineNumber":654,"sourceCode":"                \"kt_activation_policy\": self.get_kt_activation_policy(),\n                \"kt_train_mode\": \"lora\",\n                \"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(","sourceCodeStart":636,"sourceCodeEnd":672,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/hparams/model_args.py#L636-L672","documentation":"Raised by _resolve_kt_adapter_artifact_dir when adapter_folder resolves (after realpath) to a location outside the adapter root directory. The commonpath guard prevents path-traversal style folders like ../../elsewhere from redirecting KT's artifact lookup outside the declared adapter.","triggerScenarios":"Setting adapter_name_or_path: /data/adapter together with adapter_folder: ../../other/checkpoint; os.path.commonpath of the resolved paths differs from the adapter root, so the guard fires.","commonSituations":"Users try to point adapter_folder at a checkpoint saved elsewhere on disk (e.g. a shared step-500 dir) instead of a subfolder of the adapter root.","solutions":["Make `adapter_folder` a relative subfolder of the adapter root, e.g. `checkpoint-500`.","Or drop `adapter_folder` and set `adapter_name_or_path` directly to the exact directory containing the adapter."],"exampleFix":"# before (yaml)\nadapter_name_or_path: saves/lora_v2\nadapter_folder: ../../other_run/checkpoint-500\n\n# after (yaml)\nadapter_name_or_path: saves/lora_v2\nadapter_folder: checkpoint-500","handlingStrategy":"validation","validationCode":"import os\nroot = os.path.realpath(os.path.expanduser(cfg['adapter_name_or_path'][0]))\ntarget = os.path.realpath(os.path.join(root, cfg.get('adapter_folder') or ''))\nif os.path.commonpath((root, target)) != root:\n    raise SystemExit('adapter_folder escapes the adapter directory')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat adapter_folder as strictly relative to the adapter root.","Symlink then realpath-check suspicious paths before launch."],"tags":["ktransformers","adapter","path-traversal","config"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}