hiyouga/LlamaFactory · error · ValueError

Adapter is only valid for the LoRA method.

Error message

Adapter is only valid for the LoRA method.

What it means

Raised by _verify_model_args when adapter_name_or_path is set but finetuning_type is not 'lora'. Adapters in LlamaFactory are LoRA (or OFT-style) delta weights; loading them only makes sense when the run itself uses the LoRA method, so any other finetuning_type combined with an adapter path is rejected.

Source

Thrown at src/llamafactory/hparams/parser.py:233

        transformers.utils.logging.enable_default_handler()
        transformers.utils.logging.enable_explicit_format()


def _set_env_vars() -> None:
    if is_torch_npu_available():
        # avoid JIT compile on NPU devices, see https://zhuanlan.zhihu.com/p/660875458
        torch.npu.set_compile_mode(jit_compile=is_env_enabled("NPU_JIT_COMPILE"))
        # avoid use fork method on NPU devices, see https://github.com/hiyouga/LLaMA-Factory/issues/7447
        os.environ["VLLM_WORKER_MULTIPROC_METHOD"] = "spawn"


def _verify_model_args(
    model_args: "ModelArguments",
    data_args: "DataArguments",
    finetuning_args: "FinetuningArguments",
) -> None:
    if model_args.adapter_name_or_path is not None and finetuning_args.finetuning_type != "lora":
        raise ValueError("Adapter is only valid for the LoRA method.")

    if model_args.quantization_bit is not None:
        if finetuning_args.finetuning_type not in ["lora", "oft"]:
            raise ValueError("Quantization is only compatible with the LoRA or OFT method.")

        if finetuning_args.pissa_init:
            raise ValueError("Please use scripts/pissa_init.py to initialize PiSSA for a quantized model.")

        if model_args.resize_vocab:
            raise ValueError("Cannot resize embedding layers of a quantized model.")

        if model_args.adapter_name_or_path is not None and finetuning_args.create_new_adapter:
            raise ValueError("Cannot create new adapter upon a quantized model.")

        if model_args.adapter_name_or_path is not None and len(model_args.adapter_name_or_path) != 1:
            raise ValueError("Quantized model only accepts a single adapter. Merge them first.")

View on GitHub (pinned to f28afaf635)

Solutions

1. Set `finetuning_type: lora` when specifying `adapter_name_or_path`.
2. Or remove `adapter_name_or_path` if you truly want full/freeze finetuning from the base weights.

Example fix

# before (yaml)
finetuning_type: full
adapter_name_or_path: saves/lora_v1

# after (yaml)
finetuning_type: lora
adapter_name_or_path: saves/lora_v1

if cfg.get('adapter_name_or_path') and cfg.get('finetuning_type') != 'lora':
    raise SystemExit('adapters require finetuning_type: lora')

def uses_adapter_with_lora(cfg: dict) -> bool:
    return not cfg.get('adapter_name_or_path') or cfg.get('finetuning_type') == 'lora'

When it happens

Trigger: A YAML with adapter_name_or_path: saves/lora_v1 while finetuning_type: full (or freeze); _verify_model_args runs during get_train_args/get_infer_args before model loading.

Common situations: Continuing from a LoRA run but flipping to full finetuning while leaving the adapter path behind; or eval configs that set the adapter but forget finetuning_type: lora.

Related errors

• KTransformers thin integration currently supports LoRA finet
• KTransformers accepts a single `adapter_name_or_path`.
• Cannot create new adapter upon a quantized model.
• `reward_model_type` cannot be lora for Freeze/Full PPO train
• Cannot use LoRA with GaLore, APOLLO or BAdam together.

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