{"record":{"id":"aba9cadeb8e6ecbf","repo":"hiyouga/LlamaFactory","slug":"megatron-bridge-is-required-when-use-megatron-brid","errorCode":null,"errorMessage":"megatron-bridge is required when USE_MEGATRON_BRIDGE=1. Please install `megatron-bridge` and its dependencies.","messagePattern":"megatron-bridge is required when USE_MEGATRON_BRIDGE=1\\. Please install `megatron-bridge` and its dependencies\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/hparams/parser.py","lineNumber":401,"sourceCode":"        parser, args, allow_extra_keys=allow_extra_keys\n    )\n    model_args._kt_inference_config = kt_args.kt_config\n    return model_args, data_args, eval_args, finetuning_args\n\n\ndef get_ray_args(args: dict[str, Any] | list[str] | None = None) -> RayArguments:\n    parser = HfArgumentParser(RayArguments)\n    (ray_args,) = _parse_args(parser, args, allow_extra_keys=True)\n    return ray_args\n\n\ndef get_train_args(args: dict[str, Any] | list[str] | None = None) -> _TRAIN_CLS:\n    mb_args = None\n    if is_env_enabled(\"USE_MCA\"):\n        model_args, data_args, training_args, finetuning_args, generating_args = _parse_train_mca_args(args)\n    elif is_env_enabled(\"USE_MEGATRON_BRIDGE\"):\n        if not is_megatron_bridge_available():\n            raise ImportError(\n                \"megatron-bridge is required when USE_MEGATRON_BRIDGE=1. \"\n                \"Please install `megatron-bridge` and its dependencies.\"\n            )\n        model_args, data_args, training_args, finetuning_args, mb_args, generating_args = _parse_train_mbridge_args(\n            args\n        )\n    else:\n        model_args, data_args, training_args, finetuning_args, generating_args = _parse_train_args(args)\n        finetuning_args.use_mca = False\n        finetuning_args.use_megatron_bridge = False\n\n    # Setup logging\n    if training_args.should_log:\n        _set_transformers_logging()\n\n    # Check arguments\n    if finetuning_args.stage != \"sft\":\n        if training_args.predict_with_generate:","sourceCodeStart":383,"sourceCodeEnd":419,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/hparams/parser.py#L383-L419","documentation":"This ImportError is raised in get_train_args when the environment variable USE_MEGATRON_BRIDGE=1 is set but the optional megatron-bridge package is not importable (is_megatron_bridge_available() returns False). Megatron Bridge is an optional backend, so the dependency check runs before _parse_train_mbridge_args parses its arguments.","triggerScenarios":"Running any train command with USE_MEGATRON_BRIDGE=1 in an environment where megatron-bridge (and its Megatron dependencies) is not installed — e.g. a fresh venv, a container built from the base LlamaFactory image, or after downgrading/uninstalling extras.","commonSituations":"CI jobs or Docker images that set USE_MEGATRON_BRIDGE=1 globally while the image only includes the base requirements; following Megatron Bridge docs on a machine where only pip install llamafactory was run; stale shell profile exporting the variable from earlier experiments.","solutions":["Install the backend: pip install megatron-bridge (or the documented extras, e.g. pip install llamafactory[megatron] / requirements listed in the Megatron Bridge docs).","If you did not intend Megatron Bridge, unset the variable: unset USE_MEGATRON_BRIDGE (or remove it from .env / CI env) and re-run.","Verify with python -c \"from llamafactory.extras import is_megatron_bridge_available\" or simply retry the command after install."],"exampleFix":"# before\nUSE_MEGATRON_BRIDGE=1 llamafactory-cli train cfg.yaml  # ImportError\n\n# after\npip install megatron-bridge\nUSE_MEGATRON_BRIDGE=1 llamafactory-cli train cfg.yaml","handlingStrategy":"validation","validationCode":"import importlib.util, os\n\nif os.environ.get(\"USE_MEGATRON_BRIDGE\") == \"1\":\n    if importlib.util.find_spec(\"megatron_bridge\") is None:\n        raise SystemExit(\"USE_MEGATRON_BRIDGE=1 requires megatron-bridge; pip install megatron-bridge\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin the megatron-bridge extra in the same requirements file as the env var usage.","Add an install-check step at the top of launcher scripts that gate on USE_MEGATRON_BRIDGE.","Never export USE_MEGATRON_BRIDGE in shell profiles; scope it per-command so unrelated environments don't hit the check."],"tags":["megatron","dependency","environment","import-error"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}