hiyouga/LlamaFactory · critical · ValueError

Please provide `model_name_or_path`.

Error message

Please provide `model_name_or_path`.

What it means

Raised in ModelArguments.__post_init__ (src/llamafactory/hparams/model_args.py:208) when model_name_or_path is None. Every LlamaFactory workflow (train/chat/api/export) needs a base model or tokenizer location; this is the first sanity check executed when the dataclass is constructed from the YAML/JSON config or CLI args.

Source

Thrown at src/llamafactory/hparams/model_args.py:208

        default=None,
        metadata={"help": "Auth token to log in with ModelScope Hub."},
    )
    om_hub_token: str | None = field(
        default=None,
        metadata={"help": "Auth token to log in with Modelers Hub."},
    )
    print_param_status: bool = field(
        default=False,
        metadata={"help": "For debugging purposes, print the status of the parameters in the model."},
    )
    trust_remote_code: bool = field(
        default=False,
        metadata={"help": "Whether to trust the execution of code from datasets/models defined on the Hub or not."},
    )

    def __post_init__(self):
        if self.model_name_or_path is None:
            raise ValueError("Please provide `model_name_or_path`.")

        if self.adapter_name_or_path is not None:  # support merging multiple lora weights
            self.adapter_name_or_path = [path.strip() for path in self.adapter_name_or_path.split(",")]

        if self.add_tokens is not None:  # support multiple tokens
            self.add_tokens = [token.strip() for token in self.add_tokens.split(",")]

        # Process special tokens with priority: new_special_tokens_config > add_special_tokens
        if self.new_special_tokens_config is not None:
            # Priority 1: Load from YAML config (extracts both tokens and descriptions)
            try:
                cfg = OmegaConf.load(self.new_special_tokens_config)
                token_descriptions = OmegaConf.to_container(cfg)

                if not isinstance(token_descriptions, dict):
                    raise ValueError(
                        f"YAML config must be a dictionary mapping tokens to descriptions. "
                        f"Got: {type(token_descriptions)}"

View on GitHub (pinned to f28afaf635)

Solutions

1. Add model_name_or_path (a Hub repo id, local dir, or checkpoint path) to the top level of your training/chat/export YAML
2. Check exact spelling: the key is model_name_or_path
3. If templating, ensure undefined variables render to a real default instead of dropping the key

Example fix

# before
### model
# model_name_or_path: meta-llama/Llama-3-8B-Instruct

# after
model_name_or_path: meta-llama/Llama-3-8B-Instruct

assert cfg.get('model_name_or_path'), 'model_name_or_path is required before launching'
# optionally verify early:
# from huggingface_hub import model_info; model_info(cfg['model_name_or_path'])

def has_model(cfg: dict) -> bool:
    return bool(cfg.get('model_name_or_path'))

When it happens

Trigger: Launching train/chat/export with a config that omits model_name_or_path; providing it under a misspelled key (model_name_or_paths, model_path); an empty string is accepted, but None from a missing key is not; programmatic get_model_args calls with no model key.

Common situations: Quick test configs copied from examples with the model line deleted; template rendering that drops the field when a variable is undefined; merging YAML files where an anchor overrides the model key to null.

Related errors

• `virtual_pipeline_model_parallel_size` must be >= 1 when set
• `sequence_parallel` requires `tensor_model_parallel_size` >
• YAML config must be a dictionary mapping tokens to descripti
• `image_max_pixels` cannot be smaller than `image_min_pixels`
• `video_max_pixels` cannot be smaller than `video_min_pixels`

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