hiyouga/LlamaFactory · critical · ImportError

mcore_adapter is required when USE_MCA=1. Please install `mc

Error message

mcore_adapter is required when USE_MCA=1. Please install `mcore_adapter` and its dependencies.

What it means

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.

Source

Thrown at src/llamafactory/hparams/training_args.py:28

# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

import json
from dataclasses import dataclass, field
from typing import Optional

from transformers import Seq2SeqTrainingArguments
from transformers.training_args import _convert_str_dict

from ..extras.misc import is_env_enabled, use_ray
from ..extras.packages import is_mcore_adapter_available


if is_env_enabled("USE_MCA"):
    if not is_mcore_adapter_available():
        raise ImportError(
            "mcore_adapter is required when USE_MCA=1. Please install `mcore_adapter` and its dependencies."
        )

    from mcore_adapter import Seq2SeqTrainingArguments as McaSeq2SeqTrainingArguments

    BaseTrainingArguments = McaSeq2SeqTrainingArguments
else:
    BaseTrainingArguments = Seq2SeqTrainingArguments


@dataclass
class RayArguments:
    r"""Arguments pertaining to the Ray training."""

    ray_num_workers: int = field(
        default=1,
        metadata={"help": "The number of workers for Ray training. Default is 1 worker."},
    )

View on GitHub (pinned to f28afaf635)

Solutions

1. 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.
2. If you did not intend Megatron training, unset the variable: USE_MCA= (or remove it from .env / shell profile / launch script).
3. Verify with python -c "from mcore_adapter import Seq2SeqTrainingArguments" that the install is importable before relaunching.

Example fix

# before
USE_MCA=1 llamafactory-cli train config.yaml  # ImportError

# after
pip install mcore-adapter && USE_MCA=1 llamafactory-cli train config.yaml
# or: unset USE_MCA

import os
if os.environ.get("USE_MCA", "").lower() in ("1", "true", "yes"):
    try:
        import mcore_adapter  # noqa: F401
    except ImportError:
        raise SystemExit("Install mcore-adapter or unset USE_MCA before launching")

try:
    from llamafactory.hparams.training_args import TrainingArguments
except ImportError as e:
    if 'mcore_adapter' in str(e):
        print('USE_MCA requires mcore-adapter: pip install mcore-adapter, or unset USE_MCA')
    raise

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• megatron-bridge is required when USE_MEGATRON_BRIDGE=1. Plea
• Pipeline parallel size should be smaller than the number of
• Megatron Bridge arguments are missing. Please set USE_MEGATR
• The installed kt-kernel does not provide the activation chec
• Qwen2VL requires 3D position ids for mrope.

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