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

The Megatron-Bridge path (src/llamafactory/train/tuner.py:112) expects `finetuning_args.megatron_bridge_args` to be populated; it is derived from the `USE_MEGATRON_BRIDGE=1` environment flow. If the flag enabled the bridge but the Megatron Bridge argument object is None, the run aborts with this ValueError.

Source

Thrown at src/llamafactory/train/tuner.py:112

            raise ImportError("hyper_parallel is not installed. Please install it with `pip install hyper_parallel`.")
        if finetuning_args.stage == "pt":
            from .hyper_parallel import run_pt as run_pt_hp

            run_pt_hp(model_args, data_args, training_args, finetuning_args, callbacks)
        else:
            from .hyper_parallel import run_sft as run_sft_hp

            run_sft_hp(model_args, data_args, training_args, finetuning_args, generating_args, callbacks)

    elif finetuning_args.stage in ["pt", "sft"] and finetuning_args.use_megatron_bridge:
        if not is_megatron_bridge_available():
            raise ImportError(
                "megatron-bridge is not installed. "
                "Please install it with `pip install --no-build-isolation megatron-bridge`."
            )
        mb_args = finetuning_args.megatron_bridge_args
        if mb_args is None:
            raise ValueError("Megatron Bridge arguments are missing. Please set USE_MEGATRON_BRIDGE=1.")
        if finetuning_args.stage == "pt":
            from .megatron_bridge import run_pt as run_pt_mb

            run_pt_mb(model_args, data_args, training_args, finetuning_args, mb_args, callbacks)
        else:
            from .megatron_bridge import run_sft as run_sft_mb

            run_sft_mb(model_args, data_args, training_args, finetuning_args, mb_args, callbacks)

    elif finetuning_args.stage in ["pt", "sft", "dpo"] and finetuning_args.use_mca:
        if not is_mcore_adapter_available():
            raise ImportError("mcore_adapter is not installed. Please install it with `pip install mcore-adapter`.")
        if finetuning_args.stage == "pt":
            from .mca import run_pt as run_pt_mca

            run_pt_mca(model_args, data_args, training_args, finetuning_args, callbacks)
        elif finetuning_args.stage == "sft":
            from .mca import run_sft as run_sft_mca

View on GitHub (pinned to f28afaf635)

Solutions

1. Launch via the supported path with `USE_MEGATRON_BRIDGE=1` exported before `llamafactory-cli train` so megatron_bridge_args get built.
2. If building args programmatically, populate finetuning_args.megatron_bridge_args from the megatron-bridge config loader instead of leaving it None.
3. As a fallback, disable use_megatron_bridge and use the standard trainer.

Example fix

# shell
# before
llamafactory-cli train config.yaml   # use_megatron_bridge: true but no env

# after
USE_MEGATRON_BRIDGE=1 llamafactory-cli train config.yaml

def bridge_args_ok(finetuning_args) -> bool:
    return (not finetuning_args.use_megatron_bridge) or (finetuning_args.megatron_bridge_args is not None)

When it happens

Trigger: Setting `use_megatron_bridge: true` (or the env-driven path) without going through the mechanism that constructs megatron_bridge_args — e.g. hand-editing a config or calling run_exp programmatically without USE_MEGATRON_BRIDGE=1.

Common situations: Programmatic invocations that pass a partial args dict; env var set inconsistently between the process that parsed args and the one that trains.

Related errors

• Invalid API key.
• `tensor_model_parallel_size` must be >= 1.
• `pipeline_model_parallel_size` must be >= 1.
• `expert_model_parallel_size` must be >= 1.
• `context_parallel_size` must be >= 1.

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