{"record":{"id":"31522907c9774a4d","repo":"hiyouga/LlamaFactory","slug":"multimodal-plugin-name-not-found","errorCode":null,"errorMessage":"Multimodal plugin `{name}` not found.","messagePattern":"Multimodal plugin `(.+?)` not found\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/data/mm_plugin.py","lineNumber":3291,"sourceCode":"\ndef register_mm_plugin(name: str, plugin_class: type[\"BasePlugin\"]) -> None:\n    r\"\"\"Register a multimodal plugin.\"\"\"\n    if name in PLUGINS:\n        raise ValueError(f\"Multimodal plugin {name} already exists.\")\n\n    PLUGINS[name] = plugin_class\n\n\ndef get_mm_plugin(\n    name: str,\n    image_token: str | None = None,\n    video_token: str | None = None,\n    audio_token: str | None = None,\n    **kwargs,\n) -> \"BasePlugin\":\n    r\"\"\"Get plugin for multimodal inputs.\"\"\"\n    if name not in PLUGINS:\n        raise ValueError(f\"Multimodal plugin `{name}` not found.\")\n\n    return PLUGINS[name](image_token, video_token, audio_token, **kwargs)\n","sourceCodeStart":3273,"sourceCodeEnd":3294,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/data/mm_plugin.py#L3273-L3294","documentation":"get_mm_plugin raises when the requested name is not in the PLUGINS registry. The name comes from template config (e.g. mm_plugin: xxx in the YAML) and must exactly match a built-in plugin key or a previously registered custom plugin.","triggerScenarios":"YAML/CLI specifying mm_plugin: qwen2vl (missing underscore), a typo, a plugin name from a newer/older LlamaFactory version, or a custom plugin registered after (never before) get_mm_plugin is called.","commonSituations":"Version drift: config written for a version whose plugin list differs; typos in template JSON/YAML; forgetting to call register_mm_plugin for a custom class before the template loads.","solutions":["Fix the name to an existing key — inspect `from llamafactory.data.mm_plugin import PLUGINS; print(PLUGINS.keys())`.","Upgrade/downgrade LlamaFactory to the version that provides the plugin you configured.","For custom plugins, call register_mm_plugin(name, cls) before any template referencing it is parsed."],"exampleFix":"### before\nmm_plugin: qwen2vl\n### after\nmm_plugin: qwen2_vl","handlingStrategy":"validation","validationCode":"from llamafactory.data.mm_plugin import PLUGINS\nassert mm_plugin_name in PLUGINS, f'unknown plugin {mm_plugin_name!r}; available: {sorted(PLUGINS)}'","typeGuard":"def is_known_plugin(name: str) -> bool:\n    from llamafactory.data.mm_plugin import PLUGINS\n    return name in PLUGINS","tryCatchPattern":"try:\n    plugin = get_mm_plugin(name=mm_plugin_name, ...)\nexcept ValueError as e:\n    if 'not found' in str(e):\n        raise SystemExit(f'{mm_plugin_name!r} unknown. Known: {sorted(PLUGINS)}') from e\n    raise","preventionTips":["Validate config against PLUGINS.keys() at config-load time.","Pin the LlamaFactory version your configs were written for."],"tags":["plugin-registry","multimodal","config-typo","version-compat"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}