hiyouga/LlamaFactory · error · ValueError

Please set adapter_name_or_path to merge adapters into base

Error message

Please set adapter_name_or_path to merge adapters into base model.

What it means

Merging adapters requires loading the LoRA weights onto the base model; merge_and_export_model therefore requires adapter_name_or_path inside the peft_config. Without an adapter there is nothing to merge and the call is rejected. This is separate from training-time adapter paths in model args.

Source

Thrown at src/llamafactory/v1/plugins/model_plugins/peft.py:314

    )

    return model


def merge_and_export_model(args: InputArgument = None):
    model_args, _, _, _ = get_args(args)

    raw_config = model_args.peft_config
    if raw_config is None:
        raise ValueError("Please specify peft_config to merge and export model.")
    if raw_config.name != "lora":
        raise ValueError("Currently merge and export model function is only supported for lora.")

    export_peft_config = PeftPlugin.parse_params(raw_config, LoraParams)
    if export_peft_config.export_dir is None:
        raise ValueError("Please specify export_dir.")
    if export_peft_config.adapter_name_or_path is None:
        raise ValueError("Please set adapter_name_or_path to merge adapters into base model.")

    logger.info_rank0("Loading model for export...")
    model_engine = ModelEngine(model_args, is_train=False)
    model = model_engine.model
    tokenizer = model_engine.processor

    if export_peft_config.infer_dtype == "auto":
        if model.config.torch_dtype == torch.float32 and torch.cuda.is_bf16_supported():
            model = model.to(torch.bfloat16)
            logger.info_rank0("Converted model to bfloat16.")
    else:
        target_dtype = getattr(torch, export_peft_config.infer_dtype)
        model = model.to(target_dtype)
        logger.info_rank0(f"Converted model to {export_peft_config.infer_dtype}.")

    logger.info_rank0(f"Exporting model to {export_peft_config.export_dir}...")
    model.save_pretrained(
        export_peft_config.export_dir,

View on GitHub (pinned to f28afaf635)

Solutions

1. Set adapter_name_or_path inside peft_config to the saved adapter directory (e.g. outputs/sft/checkpoint-500)
2. Point at the specific checkpoint folder that contains adapter_model.safetensors, not the run root
3. For multiple adapters, provide the list in the order they were trained

Example fix

# before
peft_config:
  name: lora
  export_dir: outputs/merged

# after
peft_config:
  name: lora
  export_dir: outputs/merged
  adapter_name_or_path: outputs/sft/checkpoint-500

pc = raw.get("peft_config", {})
adapter = pc.get("adapter_name_or_path")
assert adapter and os.path.isdir(adapter) and any("adapter_model" in f for f in os.listdir(adapter)), \
    "adapter_name_or_path must point at a saved LoRA checkpoint dir"

When it happens

Trigger: Export config has peft_config.name=lora and export_dir set, but no adapter_name_or_path inside peft_config.

Common situations: User lists adapter paths only at the top level (model_args.adapter_name_or_path) or in a training section, not inside the peft_config used for export; or points to an output_dir without choosing the checkpoint subdir.

Related errors

• Currently merge and export model function is only supported
• When `adapter_name_or_path` is provided for training, only a
• Please specify peft_config to merge and export model.
• Please specify export_dir.
• vLLM only accepts a single adapter. Merge them first.

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