{"record":{"id":"c241f9c0e733f153","repo":"hiyouga/LlamaFactory","slug":"megatron-bridge-arguments-are-missing-please-set-c241f9","errorCode":null,"errorMessage":"Megatron Bridge arguments are missing. Please set USE_MEGATRON_BRIDGE=1.","messagePattern":"Megatron Bridge arguments are missing\\. Please set USE_MEGATRON_BRIDGE=1\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/train/tuner.py","lineNumber":112,"sourceCode":"            raise ImportError(\"hyper_parallel is not installed. Please install it with `pip install hyper_parallel`.\")\n        if finetuning_args.stage == \"pt\":\n            from .hyper_parallel import run_pt as run_pt_hp\n\n            run_pt_hp(model_args, data_args, training_args, finetuning_args, callbacks)\n        else:\n            from .hyper_parallel import run_sft as run_sft_hp\n\n            run_sft_hp(model_args, data_args, training_args, finetuning_args, generating_args, callbacks)\n\n    elif finetuning_args.stage in [\"pt\", \"sft\"] and finetuning_args.use_megatron_bridge:\n        if not is_megatron_bridge_available():\n            raise ImportError(\n                \"megatron-bridge is not installed. \"\n                \"Please install it with `pip install --no-build-isolation megatron-bridge`.\"\n            )\n        mb_args = finetuning_args.megatron_bridge_args\n        if mb_args is None:\n            raise ValueError(\"Megatron Bridge arguments are missing. Please set USE_MEGATRON_BRIDGE=1.\")\n        if finetuning_args.stage == \"pt\":\n            from .megatron_bridge import run_pt as run_pt_mb\n\n            run_pt_mb(model_args, data_args, training_args, finetuning_args, mb_args, callbacks)\n        else:\n            from .megatron_bridge import run_sft as run_sft_mb\n\n            run_sft_mb(model_args, data_args, training_args, finetuning_args, mb_args, callbacks)\n\n    elif finetuning_args.stage in [\"pt\", \"sft\", \"dpo\"] and finetuning_args.use_mca:\n        if not is_mcore_adapter_available():\n            raise ImportError(\"mcore_adapter is not installed. Please install it with `pip install mcore-adapter`.\")\n        if finetuning_args.stage == \"pt\":\n            from .mca import run_pt as run_pt_mca\n\n            run_pt_mca(model_args, data_args, training_args, finetuning_args, callbacks)\n        elif finetuning_args.stage == \"sft\":\n            from .mca import run_sft as run_sft_mca","sourceCodeStart":94,"sourceCodeEnd":130,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/train/tuner.py#L94-L130","documentation":"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.","triggerScenarios":"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.","commonSituations":"Programmatic invocations that pass a partial args dict; env var set inconsistently between the process that parsed args and the one that trains.","solutions":["Launch via the supported path with `USE_MEGATRON_BRIDGE=1` exported before `llamafactory-cli train` so megatron_bridge_args get built.","If building args programmatically, populate finetuning_args.megatron_bridge_args from the megatron-bridge config loader instead of leaving it None.","As a fallback, disable use_megatron_bridge and use the standard trainer."],"exampleFix":"# shell\n# before\nllamafactory-cli train config.yaml   # use_megatron_bridge: true but no env\n\n# after\nUSE_MEGATRON_BRIDGE=1 llamafactory-cli train config.yaml","handlingStrategy":"validation","validationCode":"def bridge_args_ok(finetuning_args) -> bool:\n    return (not finetuning_args.use_megatron_bridge) or (finetuning_args.megatron_bridge_args is not None)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always launch Megatron-Bridge runs with USE_MEGATRON_BRIDGE=1 exported.","Assert megatron_bridge_args is not None in config preflight when the flag is on."],"tags":["megatron","config","environment-variables"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}