hiyouga/LlamaFactory · error · ValueError

Please specify export_dir.

Error message

Please specify export_dir.

What it means

The export routine reads export_dir from the parsed LoRA peft_config to know where to write the merged model; without it there is no destination and it aborts before loading the model. It is a required field of the export flow, distinct from training output_dir.

Source

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

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

View on GitHub (pinned to f28afaf635)

Solutions

1. Add export_dir under peft_config in the export YAML
2. Make sure it is not nested at the top level of the file
3. Ensure the directory is writable and has enough disk space for a full-precision merge

Example fix

# before
peft_config:
  name: lora
  adapter_name_or_path: outputs/sft

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

pc = raw.get("peft_config", {})
assert pc.get("export_dir"), "peft_config.export_dir is required for merge-and-export"

When it happens

Trigger: peft_config exists with name lora and adapter paths, but export_dir key is missing from the peft_config section.

Common situations: User puts the destination in top-level export_dir or output_dir instead of under peft_config; or copies a training YAML and forgets the export-specific keys.

Related errors

• Please specify peft_config to merge and export model.
• Currently merge and export model function is only supported
• Please set adapter_name_or_path to merge adapters into base
• When `adapter_name_or_path` is provided for training, only a
• Current model does not support freeze tuning.

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