{"record":{"id":"a9a273056a6b9f15","repo":"hiyouga/LlamaFactory","slug":"both-hf-path-and-dcp-path-are-required","errorCode":null,"errorMessage":"Both 'hf_path' and 'dcp_path' are required.","messagePattern":"Both 'hf_path' and 'dcp_path' are required\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"scripts/hf2dcp.py","lineNumber":40,"sourceCode":"  dcp_path: Output path (directory) for DCP checkpoint.\n\"\"\"\n\nimport fire\nimport torch\nimport torch.distributed.checkpoint as dcp\nimport transformers\nfrom transformers import AutoConfig\n\n\ndef convert(hf_path: str, dcp_path: str) -> None:\n    \"\"\"Convert HF model weights to DCP.\n\n    Args:\n        hf_path: HuggingFace model directory.\n        dcp_path: Output path (directory) for DCP checkpoint.\n    \"\"\"\n    if not hf_path or not dcp_path:\n        raise ValueError(\"Both 'hf_path' and 'dcp_path' are required.\")\n\n    print(f\"Loading HF model from {hf_path}...\")\n    config = AutoConfig.from_pretrained(hf_path)\n    architectures = getattr(config, \"architectures\", [])\n    if architectures:\n        model_cls = getattr(transformers, architectures[0], transformers.AutoModelForCausalLM)\n    else:\n        model_cls = transformers.AutoModelForCausalLM\n\n    model = model_cls.from_pretrained(hf_path, device_map=\"cpu\", torch_dtype=torch.bfloat16)\n\n    print(f\"Saving to DCP format at {dcp_path}...\")\n    dcp.save(model.state_dict(), checkpoint_id=dcp_path)\n    print(\"Done!\")\n\n\ndef help() -> None:\n    \"\"\"Show help message.\"\"\"","sourceCodeStart":22,"sourceCodeEnd":58,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/scripts/hf2dcp.py#L22-L58","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["pip install -U 'transformers>=4.58.0'","Or install the pinned commit: pip install git+https://github.com/huggingface/transformers.git@3c2517727ce28a30f5044e01663ee204deb1cdbe"],"exampleFix":"# before\ntransformers==4.57.1 + lfm2_vl model -> RuntimeError\n\n# after\npip install -U 'transformers>=4.58.0'\n# or\npip install git+https://github.com/huggingface/transformers.git@3c2517727ce28a30f5044e01663ee204deb1cdbe","handlingStrategy":"validation","validationCode":"from transformers import AutoConfig\nfrom llamafactory.extras.packages import is_transformers_version_greater_than\nif AutoConfig.from_pretrained(model_path).model_type == 'lfm2_vl':\n    assert is_transformers_version_greater_than('4.58.0'), 'pip install -U \\'transformers>=4.58.0\\''","typeGuard":"def lfm2_vl_supported() -> bool:\n    from llamafactory.extras.packages import is_transformers_version_greater_than\n    return is_transformers_version_greater_than('4.58.0')","tryCatchPattern":"try:\n    run_sft(train_args)\nexcept RuntimeError as e:\n    if 'LFM2.5-VL' in str(e):\n        raise SystemExit('Upgrade transformers to >=4.58.0 or the pinned git commit') from e\n    raise","preventionTips":["Track transformers release notes for new model types before adopting them","Automate: assert minimum transformers version per model_type in your launcher"],"tags":["version","transformers","lfm2-vl","dependency"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}