hiyouga/LlamaFactory · error · ValueError

Multimodal plugin `{name}` not found.

Error message

Multimodal plugin `{name}` not found.

What it means

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.

Source

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

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. Fix the name to an existing key — inspect `from llamafactory.data.mm_plugin import PLUGINS; print(PLUGINS.keys())`.
2. Upgrade/downgrade LlamaFactory to the version that provides the plugin you configured.
3. For custom plugins, call register_mm_plugin(name, cls) before any template referencing it is parsed.

Example fix

### before
mm_plugin: qwen2vl
### after
mm_plugin: qwen2_vl

from llamafactory.data.mm_plugin import PLUGINS
assert mm_plugin_name in PLUGINS, f'unknown plugin {mm_plugin_name!r}; available: {sorted(PLUGINS)}'

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

try:
    plugin = get_mm_plugin(name=mm_plugin_name, ...)
except ValueError as e:
    if 'not found' in str(e):
        raise SystemExit(f'{mm_plugin_name!r} unknown. Known: {sorted(PLUGINS)}') from e
    raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Multimodal plugin {name} already exists.
• 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/31522907c9774a4d. Report an issue: GitHub.