hiyouga/LlamaFactory · error · ValueError

Please use scripts/pissa_init.py to initialize PiSSA for a q

Error message

Please use scripts/pissa_init.py to initialize PiSSA for a quantized model.

What it means

Raised by _verify_model_args when quantization_bit is set together with pissa_init. PiSSA initialization rewrites the base weights by decomposing them (producing residual weights to export), which cannot be done in-recipe on an already-quantized model; the dedicated scripts/pissa_init.py handles the quantized case.

Source

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

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


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)

View on GitHub (pinned to f28afaf635)

Solutions

1. Run `scripts/pissa_init.py` on the model first to generate the PiSSA-initialized base + adapter, then quantize/point the training config at those outputs.
2. Or disable `pissa_init` and use plain LoRA on the quantized model.

Example fix

# before (yaml)
quantization_bit: 4
pissa_init: true

# after (bash)
python scripts/pissa_init.py --model_name_or_path meta-llama/Llama-3-8B \
  --lora_rank 16 --output_dir saves/pissa_base
# then reference saves/pissa_base in the training YAML with quantization_bit set

if cfg.get('quantization_bit') is not None and cfg.get('pissa_init'):
    raise SystemExit('use scripts/pissa_init.py for quantized models')

When it happens

Trigger: A YAML with quantization_bit: 4 plus pissa_init: true; get_train_args -> _verify_model_args rejects the pair immediately.

Common situations: Users enable PiSSA for faster LoRA convergence and quantize at the same time, not realizing PiSSA residual export must precede quantization.

Related errors

• Quantization is only compatible with the LoRA or OFT method.
• Cannot use PiSSA for current training stage.
• `pissa_init` is only valid for LoRA training.
• KTransformers uses LLaMA-Factory's `disable_gradient_checkpo
• KTransformers supplies its checkpoint context; remove `gradi

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