hiyouga/LlamaFactory · error · ValueError

Please specify peft_config to merge and export model.

Error message

Please specify peft_config to merge and export model.

What it means

merge_and_export_model in the v1 peft plugin requires a peft_config section because export parameters (adapter paths, dtype, export dir) are read from it. Calling export without any peft_config means there is nothing to merge and no export settings, so it fails fast. This usually means the YAML passed to the export command lacks the peft_config block.

Source

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

    logger.info_rank0(f"Set trainable layers: {trainable_layers}")

    # Count trainable params for verification
    trainable_params = sum(p.numel() for p in model.parameters() if p.requires_grad)
    all_params = sum(p.numel() for p in model.parameters())
    logger.info_rank0(
        f"trainable params: {trainable_params} || all params: {all_params} || trainable%: {100 * trainable_params / all_params:.4f}"
    )

    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.")

View on GitHub (pinned to f28afaf635)

Solutions

  1. Add a peft_config block to the export YAML with name: lora, export_dir, and adapter_name_or_path
  2. If you only want to convert/export a base model without adapters, use the appropriate non-peft export path instead of merge_and_export_model
  3. Verify the CLI subcommand and YAML file actually correspond (export vs train configs)

Example fix

# before
model_name_or_path: qwen/Qwen2.5-7B
export_dir: outputs/merged

# after
model_name_or_path: qwen/Qwen2.5-7B
peft_config:
  name: lora
  export_dir: outputs/merged
  adapter_name_or_path: outputs/sft/checkpoint-500
Defensive patterns

Strategy: validation

Validate before calling

raw = yaml.safe_load(open("export.yaml"))
assert raw.get("peft_config"), "export YAML requires a peft_config section (name: lora, export_dir, adapter_name_or_path)"

Prevention

When it happens

Trigger: Running export with a config file that has no peft_config key, or passing a model_args object where peft_config is None.

Common situations: User exports a merged model but wrote settings under top-level keys instead of peft_config; or reused a training YAML for a non-peft run and ran the export entry point with it.

Related errors

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