hiyouga/LlamaFactory · error · ValueError

Both 'hf_path' and 'dcp_path' are required.

Error message

Both 'hf_path' and 'dcp_path' are required.

What it means

For config.model_type == 'lfm2_vl' the patcher requires transformers >= 4.58.0 (patcher.py:416); the LiquidAI LFM2.5-VL model class was only merged upstream at that version. As an alternative it names an exact pre-release commit (3c25177) that already contains the code, for users who cannot wait for the release.

Source

Thrown at scripts/hf2dcp.py:40

  dcp_path: Output path (directory) for DCP checkpoint.
"""

import fire
import torch
import torch.distributed.checkpoint as dcp
import transformers
from transformers import AutoConfig


def convert(hf_path: str, dcp_path: str) -> None:
    """Convert HF model weights to DCP.

    Args:
        hf_path: HuggingFace model directory.
        dcp_path: Output path (directory) for DCP checkpoint.
    """
    if not hf_path or not dcp_path:
        raise ValueError("Both 'hf_path' and 'dcp_path' are required.")

    print(f"Loading HF model from {hf_path}...")
    config = AutoConfig.from_pretrained(hf_path)
    architectures = getattr(config, "architectures", [])
    if architectures:
        model_cls = getattr(transformers, architectures[0], transformers.AutoModelForCausalLM)
    else:
        model_cls = transformers.AutoModelForCausalLM

    model = model_cls.from_pretrained(hf_path, device_map="cpu", torch_dtype=torch.bfloat16)

    print(f"Saving to DCP format at {dcp_path}...")
    dcp.save(model.state_dict(), checkpoint_id=dcp_path)
    print("Done!")


def help() -> None:
    """Show help message."""

View on GitHub (pinned to f28afaf635)

Solutions

1. pip install -U 'transformers>=4.58.0'
2. Or install the pinned commit: pip install git+https://github.com/huggingface/transformers.git@3c2517727ce28a30f5044e01663ee204deb1cdbe

Example fix

# before
transformers==4.57.1 + lfm2_vl model -> RuntimeError

# after
pip install -U 'transformers>=4.58.0'
# or
pip install git+https://github.com/huggingface/transformers.git@3c2517727ce28a30f5044e01663ee204deb1cdbe

from transformers import AutoConfig
from llamafactory.extras.packages import is_transformers_version_greater_than
if AutoConfig.from_pretrained(model_path).model_type == 'lfm2_vl':
    assert is_transformers_version_greater_than('4.58.0'), 'pip install -U \'transformers>=4.58.0\''

def lfm2_vl_supported() -> bool:
    from llamafactory.extras.packages import is_transformers_version_greater_than
    return is_transformers_version_greater_than('4.58.0')

try:
    run_sft(train_args)
except RuntimeError as e:
    if 'LFM2.5-VL' in str(e):
        raise SystemExit('Upgrade transformers to >=4.58.0 or the pinned git commit') from e
    raise

When it happens

Trigger: model_name_or_path is an LFM2.5-VL checkpoint (model_type lfm2_vl) and transformers < 4.58.0 is installed; the check fires during config patching before weights load.

Common situations: Training LiquidAI LFM2.5-VL in an environment pinned to a stable transformers (e.g. 4.57) before 4.58 shipped; base images that lag the model release.

Related errors

• All 'dcp_path', 'hf_path', and 'config_path' are required.
• `num_layers` {num_layers} should be divisible by `num_expand
• Device not supported: {device_name}.
• Qwen2VL requires 3D position ids for mrope.
• Stage does not supported: {stage}.

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