hiyouga/LlamaFactory · error · ValueError

Megatron Bridge arguments are missing. Please set USE_MEGATR

Error message

Megatron Bridge arguments are missing. Please set USE_MEGATRON_BRIDGE=1.

What it means

This fires when finetuning_args.use_megatron_bridge is true but mb_args (the MegatronBridgeArguments parsed only under USE_MEGATRON_BRIDGE=1) is None — i.e. the flag was turned on through the config/parser path without going through the env-var-gated mbridge parsing branch. It guards against a half-configured bridge run.

Source

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

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

        if model_args.shift_attn:
            raise ValueError("PPO training is incompatible with S^2-Attn.")

        if finetuning_args.reward_model_type == "lora" and model_args.use_kt:
            raise ValueError("KTransformers does not support lora reward model.")

        if finetuning_args.reward_model_type == "lora" and model_args.use_unsloth:
            raise ValueError("Unsloth does not support lora reward model.")

View on GitHub (pinned to f28afaf635)

Solutions

1. Enable the backend via the environment variable: export USE_MEGATRON_BRIDGE=1 before llamafactory-cli train (this parses mb_args).
2. Remove use_megatron_bridge: true from the YAML — the parser sets it automatically based on the env var.
3. If wrapping programmatically, call the mbridge-aware entry (get_train_args with the env var set) rather than hand-building the flag.

Example fix

# before
# cfg.yaml: use_megatron_bridge: true, env has nothing
llamafactory-cli train cfg.yaml  # ValueError

# after
export USE_MEGATRON_BRIDGE=1
llamafactory-cli train cfg.yaml  # and remove use_megatron_bridge from the YAML

import os

if cfg.get("use_megatron_bridge") and os.environ.get("USE_MEGATRON_BRIDGE") != "1":
    raise SystemExit("Set env USE_MEGATRON_BRIDGE=1 (the YAML flag alone is not enough); or remove the flag from the YAML")

When it happens

Trigger: Setting use_megatron_bridge: true inside the YAML (or otherwise flipping the finetuning flag) while USE_MEGATRON_BRIDGE is not set in the environment, so _parse_train_args runs instead of _parse_train_mbridge_args and mb_args stays None.

Common situations: Users who discover the use_megatron_bridge config field and set it directly instead of the documented env var; wrapper code constructing FinetuningArguments programmatically.

Related errors

• Total Megatron Bridge parallel size ({parallel_size}) exceed
• Total Megatron Bridge parallel size ({parallel_size}) must d
• Megatron Bridge cannot be used together with MCA or HyperPar
• Megatron Bridge only supports the `pt` and `sft` stages.
• Megatron Bridge only supports `full` and `lora` finetuning.

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