hiyouga/LlamaFactory · error · ValueError

Cannot create new adapter upon a quantized model.

Error message

Cannot create new adapter upon a quantized model.

What it means

LlamaFactory refuses to create a fresh LoRA/OF(adapter on top of an already-quantized model (e.g. 4/8-bit via quantization_bit). The check fires in _check_model_args when all three of quantization_bit, adapter_name_or_path, and finetuning_args.create_new_adapter are set. Quantized weights cannot backprop into a new adapter initialization path safely, so the library blocks it at argument-parsing time, before any model is loaded.

Source

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

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


def _check_extra_dependencies(
    model_args: "ModelArguments",
    finetuning_args: "FinetuningArguments",
    training_args: Optional["TrainingArguments"] = None,
) -> None:
    if model_args.use_kt:
        check_version("kt-kernel", mandatory=True)
        check_version("transformers-kt", mandatory=True)
        check_version("accelerate-kt", mandatory=True)

    if model_args.use_unsloth:
        check_version("unsloth", mandatory=True)

View on GitHub (pinned to f28afaf635)

Solutions

1. Set create_new_adapter: false in the finetuning section so the existing adapter is resumed/trained instead of creating a new one.
2. Remove adapter_name_or_path from the config if you truly want a brand-new adapter on the quantized base model (create_new_adapter is then irrelevant).
3. If you need multiple adapters, run on the non-quantized base model, create/train adapters there, then export merged weights and quantize afterwards.
4. Merge your existing adapters into the base model first (export_model / llamafactory-cli export) and start a new adapter from the merged model.

Example fix

# before (YAML)
model_name_or_path: meta-llama/Llama-3-8B
quantization_bit: 4
adapter_name_or_path: saves/llama3_lora
finetuning_type: lora
create_new_adapter: true

# after (train a fresh adapter, no old adapter loaded)
model_name_or_path: meta-llama/Llama-3-8B
quantization_bit: 4
finetuning_type: lora
create_new_adapter: true

def check_qlora_new_adapter(cfg: dict) -> None:
    m, f = cfg.get("model", cfg), cfg.get("finetuning", cfg)
    if m.get("quantization_bit") and f.get("adapter_name_or_path") and f.get("create_new_adapter"):
        raise SystemExit("QLoRA + existing adapter + create_new_adapter is not allowed; drop adapter_name_or_path or set create_new_adapter: false")

When it happens

Trigger: A YAML/JSON train config (or CLI args) that simultaneously sets quantization_bit: 4 (or 8), adapter_name_or_path: <path(s)> (loading existing adapters), and create_new_adapter: true. Calling llamafactory-cli train with such a config raises ValueError immediately in get_train_args().

Common situations: Users iteratively training LoRA on a QLoRA setup: they load a previously trained adapter and want to add a second new adapter for another task in the same run. Copying an old QLoRA config and flipping create_new_adapter: true without removing the old adapter path is the typical mistake.

Related errors

• Quantized model only accepts a single adapter. Merge them fi
• `kt_model_max_length` must be a positive integer.
• Adapter is only valid for the LoRA method.
• Quantization is only compatible with the LoRA or OFT method.
• Unknown params for {cls.__name__}.{params_cls.__name__}: {so

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