{"record":{"id":"ec5bbd988150fce8","repo":"hiyouga/LlamaFactory","slug":"megatron-bridge-arguments-are-missing-please-set","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":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/hparams/parser.py","lineNumber":443,"sourceCode":"        if data_args.train_on_prompt or data_args.mask_history:\n            raise ValueError(\"`train_on_prompt` or `mask_history` cannot be set as True except SFT.\")\n\n    if finetuning_args.stage == \"sft\" and training_args.do_predict and not training_args.predict_with_generate:\n        raise ValueError(\"Please enable `predict_with_generate` to save model predictions.\")\n\n    if finetuning_args.use_megatron_bridge:\n        if finetuning_args.use_mca or finetuning_args.use_hyper_parallel:\n            raise ValueError(\"Megatron Bridge cannot be used together with MCA or HyperParallel.\")\n        if finetuning_args.stage not in [\"pt\", \"sft\"]:\n            raise ValueError(\"Megatron Bridge only supports the `pt` and `sft` stages.\")\n        if finetuning_args.finetuning_type not in [\"full\", \"lora\"]:\n            raise ValueError(\"Megatron Bridge only supports `full` and `lora` finetuning.\")\n        if model_args.quantization_bit is not None:\n            raise ValueError(\"Quantized models are not supported with Megatron Bridge.\")\n        if training_args.deepspeed is not None:\n            raise ValueError(\"Megatron Bridge is incompatible with DeepSpeed.\")\n        if mb_args is None:\n            raise ValueError(\"Megatron Bridge arguments are missing. Please set USE_MEGATRON_BRIDGE=1.\")\n        _validate_megatron_bridge_parallel_args(mb_args, training_args.world_size)\n        finetuning_args.megatron_bridge_args = mb_args\n\n    if finetuning_args.stage in [\"rm\", \"ppo\"] and training_args.load_best_model_at_end:\n        raise ValueError(\"RM and PPO stages do not support `load_best_model_at_end`.\")\n\n    if finetuning_args.stage == \"ppo\":\n        if not training_args.do_train:\n            raise ValueError(\"PPO training does not support evaluation, use the SFT stage to evaluate models.\")\n\n        if model_args.shift_attn:\n            raise ValueError(\"PPO training is incompatible with S^2-Attn.\")\n\n        if finetuning_args.reward_model_type == \"lora\" and model_args.use_kt:\n            raise ValueError(\"KTransformers does not support lora reward model.\")\n\n        if finetuning_args.reward_model_type == \"lora\" and model_args.use_unsloth:\n            raise ValueError(\"Unsloth does not support lora reward model.\")","sourceCodeStart":425,"sourceCodeEnd":461,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/hparams/parser.py#L425-L461","documentation":"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.","triggerScenarios":"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.","commonSituations":"Users who discover the use_megatron_bridge config field and set it directly instead of the documented env var; wrapper code constructing FinetuningArguments programmatically.","solutions":["Enable the backend via the environment variable: export USE_MEGATRON_BRIDGE=1 before llamafactory-cli train (this parses mb_args).","Remove use_megatron_bridge: true from the YAML — the parser sets it automatically based on the env var.","If wrapping programmatically, call the mbridge-aware entry (get_train_args with the env var set) rather than hand-building the flag."],"exampleFix":"# before\n# cfg.yaml: use_megatron_bridge: true, env has nothing\nllamafactory-cli train cfg.yaml  # ValueError\n\n# after\nexport USE_MEGATRON_BRIDGE=1\nllamafactory-cli train cfg.yaml  # and remove use_megatron_bridge from the YAML","handlingStrategy":"validation","validationCode":"import os\n\nif cfg.get(\"use_megatron_bridge\") and os.environ.get(\"USE_MEGATRON_BRIDGE\") != \"1\":\n    raise SystemExit(\"Set env USE_MEGATRON_BRIDGE=1 (the YAML flag alone is not enough); or remove the flag from the YAML\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Control Megatron Bridge exclusively through the env var; do not set use_megatron_bridge in YAML.","Document the env-var-first design in your team's runbook so configs stay backend-agnostic."],"tags":["megatron","config","environment","validation"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}