hiyouga/LlamaFactory · error · ValueError

KTransformers {operation} requires a local adapter directory

Error message

KTransformers {operation} requires a local adapter directory.

What it means

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.

Source

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

                "kt_full_weight_grad": False,
            }
        )
        return {key: value for key, value in kt_config.items() if value is not None}

    def _resolve_kt_adapter_artifact_dir(self, operation: str) -> str | None:
        if not self.adapter_name_or_path:
            return None
        if len(self.adapter_name_or_path) != 1:
            raise ValueError("KTransformers accepts a single `adapter_name_or_path`.")

        adapter_root = os.path.realpath(os.path.expanduser(self.adapter_name_or_path[0]))
        adapter_dir = adapter_root
        if self.adapter_folder:
            adapter_dir = os.path.realpath(os.path.join(adapter_root, self.adapter_folder))
            if os.path.commonpath((adapter_root, adapter_dir)) != adapter_root:
                raise ValueError("`adapter_folder` must stay inside the KT adapter directory.")
        if not os.path.isdir(adapter_dir):
            raise ValueError(f"KTransformers {operation} requires a local adapter directory.")
        return adapter_dir

    def apply_kt_config(self, finetuning_args: Any, training_args: Any, model_max_length: int | None) -> None:
        r"""Apply LLaMA-Factory KT args to transformers/accelerate KT integration points."""
        if not self.use_kt:
            return

        self.configure_kt_checkpointing(training_args)
        kt_config = self.get_kt_config_dict(
            finetuning_args,
            model_max_length,
            self._get_advanced_kt_config(training_args),
        )
        update_kt_config = getattr(training_args, "update_kt_config", None)
        if not callable(update_kt_config):
            raise RuntimeError(
                "The installed Transformers-KT does not provide `TrainingArguments.update_kt_config()`."
            )

View on GitHub (pinned to f28afaf635)

Solutions

1. Check the path exists: `ls <adapter_name_or_path>` and fix typos / restore the directory.
2. Download or copy the adapter to local disk first if it lives on the HF Hub.
3. If the adapter is gone, retrain or re-export before the KT run.

Example fix

# before (yaml)
use_kt: true
adapter_name_or_path: saves/lora_v2/checkpoint-500
  # dir deleted

# after (bash)
ls saves/lora_v2/  # pick an existing checkpoint
# after (yaml)
use_kt: true
adapter_name_or_path: saves/lora_v2/checkpoint-496

import os
p = cfg.get('adapter_name_or_path')
if p and not os.path.isdir(os.path.expanduser(p[0] if isinstance(p, list) else p)):
    raise SystemExit(f'adapter dir not found: {p}')

When it happens

Trigger: 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.

Common situations: Resuming an old run after cleaning saves/, or copy-pasting an adapter path valid on another machine.

Related errors

• KTransformers accepts a single `adapter_name_or_path`.
• 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

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