hiyouga/LlamaFactory · error · ValueError

Multimodal plugin {name} already exists.

Error message

Multimodal plugin {name} already exists.

What it means

register_mm_plugin raises when the plugin name is already a key in the global PLUGINS dict. The registry (qwen2_vl, qwen2_omni, minicpm_v, moss_vl, ...) is populated at import; registering under an existing name would silently replace the built-in plugin, so it is refused.

Source

Thrown at src/llamafactory/data/mm_plugin.py:3277

    "minicpm_v": MiniCPMVPlugin,
    "minicpm_v_4_6": MiniCPMV4_6Plugin,
    "mllama": MllamaPlugin,
    "moss_vl": MossVLPlugin,
    "paligemma": PaliGemmaPlugin,
    "pixtral": PixtralPlugin,
    "qwen2_audio": Qwen2AudioPlugin,
    "qwen2_omni": Qwen2OmniPlugin,
    "qwen2_vl": Qwen2VLPlugin,
    "qwen3_vl": Qwen3VLPlugin,
    "video_llava": VideoLlavaPlugin,
    "youtu_vl": YoutuVLPlugin,
}


def register_mm_plugin(name: str, plugin_class: type["BasePlugin"]) -> None:
    r"""Register a multimodal plugin."""
    if name in PLUGINS:
        raise ValueError(f"Multimodal plugin {name} already exists.")

    PLUGINS[name] = plugin_class


def get_mm_plugin(
    name: str,
    image_token: str | None = None,
    video_token: str | None = None,
    audio_token: str | None = None,
    **kwargs,
) -> "BasePlugin":
    r"""Get plugin for multimodal inputs."""
    if name not in PLUGINS:
        raise ValueError(f"Multimodal plugin `{name}` not found.")

    return PLUGINS[name](image_token, video_token, audio_token, **kwargs)

View on GitHub (pinned to f28afaf635)

Solutions

1. Choose a unique, namespaced plugin name (e.g. 'myorg_custom_vl').
2. Guard double registration: `if name not in PLUGINS: register_mm_plugin(name, cls)`.
3. Check the PLUGINS dict keys before registering to confirm the collision.

Example fix

# before
register_mm_plugin('qwen2_vl', MyPlugin)  # collides
# after
register_mm_plugin('my_org_vl', MyPlugin)
plugin = get_mm_plugin(name='my_org_vl', ...)

from llamafactory.data.mm_plugin import PLUGINS

NAME = 'my_org_vl'
if NAME not in PLUGINS:
    register_mm_plugin(NAME, MyPlugin)

def plugin_name_free(name: str) -> bool:
    from llamafactory.data.mm_plugin import PLUGINS
    return name not in PLUGINS

try:
    register_mm_plugin(name, cls)
except ValueError:
    if PLUGINS.get(name) is not cls:
        raise  # real collision with someone else's plugin

When it happens

Trigger: Calling register_mm_plugin('qwen2_vl', MyPlugin) — any built-in name collides. Also double registration if a custom registration module is imported twice (e.g. re-imported under a different path).

Common situations: Users adding a custom plugin and forgetting to pick a unique name; module-level registration executed twice due to importlib.reload or duplicated module copies.

Related errors

• Multimodal plugin `{name}` not found.
• Please upgrade `transformers` to 4.34.0
• Unable to process key {key}
• Invalid length
• Invalid input type {input_item.type}.

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