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.

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
Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

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

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

Appendix: 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)