{"record":{"id":"d0a0dbfaa9963776","repo":"hiyouga/LlamaFactory","slug":"mcore-adapter-is-required-when-use-mca-1-please-i","errorCode":null,"errorMessage":"mcore_adapter is required when USE_MCA=1. Please install `mcore_adapter` and its dependencies.","messagePattern":"mcore_adapter is required when USE_MCA=1\\. Please install `mcore_adapter` and its dependencies\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"critical","filePath":"src/llamafactory/hparams/training_args.py","lineNumber":28,"sourceCode":"# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\nimport json\nfrom dataclasses import dataclass, field\nfrom typing import Optional\n\nfrom transformers import Seq2SeqTrainingArguments\nfrom transformers.training_args import _convert_str_dict\n\nfrom ..extras.misc import is_env_enabled, use_ray\nfrom ..extras.packages import is_mcore_adapter_available\n\n\nif is_env_enabled(\"USE_MCA\"):\n    if not is_mcore_adapter_available():\n        raise ImportError(\n            \"mcore_adapter is required when USE_MCA=1. Please install `mcore_adapter` and its dependencies.\"\n        )\n\n    from mcore_adapter import Seq2SeqTrainingArguments as McaSeq2SeqTrainingArguments\n\n    BaseTrainingArguments = McaSeq2SeqTrainingArguments\nelse:\n    BaseTrainingArguments = Seq2SeqTrainingArguments\n\n\n@dataclass\nclass RayArguments:\n    r\"\"\"Arguments pertaining to the Ray training.\"\"\"\n\n    ray_num_workers: int = field(\n        default=1,\n        metadata={\"help\": \"The number of workers for Ray training. Default is 1 worker.\"},\n    )","sourceCodeStart":10,"sourceCodeEnd":46,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/hparams/training_args.py#L10-L46","documentation":"Raised at import time of training_args.py when the environment variable USE_MCA is truthy but the mcore_adapter package is not installed. With USE_MCA the TrainingArguments base class is swapped for Megatron-core's Seq2SeqTrainingArguments, so the dependency is mandatory before any argument parsing happens.","triggerScenarios":"Exporting USE_MCA=1 (or true) and then running any llamafactory-cli command in an environment where import of mcore_adapter fails (is_mcore_adapter_available() returns False).","commonSituations":"Enabling Megatron-core training without installing the extra package; a fresh environment or CI image that lacks mcore_adapter; a broken mcore_adapter install whose import raises.","solutions":["Install mcore_adapter and its dependencies (e.g. pip install mcore-adapter or install from its source repo) in the environment where USE_MCA is set.","If you did not intend Megatron training, unset the variable: USE_MCA= (or remove it from .env / shell profile / launch script).","Verify with python -c \"from mcore_adapter import Seq2SeqTrainingArguments\" that the install is importable before relaunching."],"exampleFix":"# before\nUSE_MCA=1 llamafactory-cli train config.yaml  # ImportError\n\n# after\npip install mcore-adapter && USE_MCA=1 llamafactory-cli train config.yaml\n# or: unset USE_MCA","handlingStrategy":"validation","validationCode":"import os\nif os.environ.get(\"USE_MCA\", \"\").lower() in (\"1\", \"true\", \"yes\"):\n    try:\n        import mcore_adapter  # noqa: F401\n    except ImportError:\n        raise SystemExit(\"Install mcore-adapter or unset USE_MCA before launching\")","typeGuard":null,"tryCatchPattern":"try:\n    from llamafactory.hparams.training_args import TrainingArguments\nexcept ImportError as e:\n    if 'mcore_adapter' in str(e):\n        print('USE_MCA requires mcore-adapter: pip install mcore-adapter, or unset USE_MCA')\n    raise","preventionTips":["Add mcore-adapter to the environment/requirements whenever USE_MCA is exported in project scripts.","Set USE_MCA per-command instead of globally so unrelated environments never see it."],"tags":["megatron","mca","environment","import-error","dependency"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}