hiyouga/LlamaFactory · error · ValueError

Megatron Bridge only supports the `pt` and `sft` stages.

Error message

Megatron Bridge only supports the `pt` and `sft` stages.

What it means

The Megatron Bridge backend only implements pretraining (pt) and supervised fine-tuning (sft). Preference tuning (dpo/kto), reward modeling (rm), and PPO have no Megatron training loop in this integration, so the parser rejects any other stage when use_megatron_bridge is true.

Source

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

    # Check arguments
    if finetuning_args.stage != "sft":
        if training_args.predict_with_generate:
            raise ValueError("`predict_with_generate` cannot be set as True except SFT.")

        if data_args.neat_packing:
            raise ValueError("`neat_packing` cannot be set as True except SFT.")

        if data_args.train_on_prompt or data_args.mask_history:
            raise ValueError("`train_on_prompt` or `mask_history` cannot be set as True except SFT.")

    if finetuning_args.stage == "sft" and training_args.do_predict and not training_args.predict_with_generate:
        raise ValueError("Please enable `predict_with_generate` to save model predictions.")

    if finetuning_args.use_megatron_bridge:
        if finetuning_args.use_mca or finetuning_args.use_hyper_parallel:
            raise ValueError("Megatron Bridge cannot be used together with MCA or HyperParallel.")
        if finetuning_args.stage not in ["pt", "sft"]:
            raise ValueError("Megatron Bridge only supports the `pt` and `sft` stages.")
        if finetuning_args.finetuning_type not in ["full", "lora"]:
            raise ValueError("Megatron Bridge only supports `full` and `lora` finetuning.")
        if model_args.quantization_bit is not None:
            raise ValueError("Quantized models are not supported with Megatron Bridge.")
        if training_args.deepspeed is not None:
            raise ValueError("Megatron Bridge is incompatible with DeepSpeed.")
        if mb_args is None:
            raise ValueError("Megatron Bridge arguments are missing. Please set USE_MEGATRON_BRIDGE=1.")
        _validate_megatron_bridge_parallel_args(mb_args, training_args.world_size)
        finetuning_args.megatron_bridge_args = mb_args

    if finetuning_args.stage in ["rm", "ppo"] and training_args.load_best_model_at_end:
        raise ValueError("RM and PPO stages do not support `load_best_model_at_end`.")

    if finetuning_args.stage == "ppo":
        if not training_args.do_train:
            raise ValueError("PPO training does not support evaluation, use the SFT stage to evaluate models.")

View on GitHub (pinned to f28afaf635)

Solutions

1. Change stage to sft or pt for Megatron Bridge runs.
2. Unset USE_MEGATRON_BRIDGE for DPO/RM/PPO/KTO jobs so they run on the standard HF trainer.
3. Keep per-stage launcher scripts/wrappers that set the right env var per task.

Example fix

# before
export USE_MEGATRON_BRIDGE=1
# cfg.yaml: stage: dpo

# after (option 1: run DPO on standard backend)
unset USE_MEGATRON_BRIDGE
# cfg.yaml unchanged

# after (option 2: stay on bridge)
# cfg.yaml: stage: sft

import os

if os.environ.get("USE_MEGATRON_BRIDGE") == "1" and cfg.get("stage", "sft") not in ("pt", "sft"):
    raise SystemExit("Megatron Bridge supports only pt/sft stages; unset USE_MEGATRON_BRIDGE for this run")

When it happens

Trigger: USE_MEGATRON_BRIDGE=1 with stage: dpo (or rm, ppo, kto) in the train config; get_train_args() reaches the Megatron Bridge validation block and raises before parsing proceeds further.

Common situations: Enabling the bridge globally (exported env var) and then launching a DPO job from an unrelated config; assuming Megatron supports all LlamaFactory stages because the CLI accepts them.

Related errors

• Total Megatron Bridge parallel size ({parallel_size}) exceed
• Total Megatron Bridge parallel size ({parallel_size}) must d
• `predict_with_generate` cannot be set as True except SFT.
• `neat_packing` cannot be set as True except SFT.
• `train_on_prompt` or `mask_history` cannot be set as True ex

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