reflex-dev/reflex · error · InvalidPluginConfigError

reflex.Config.plugins must contain Plugin instances, but got

Error message

reflex.Config.plugins must contain Plugin instances, but got {entry!r} of type {type(entry).__name__}. Pass an instance, e.g. plugins=[SitemapPlugin()].

What it means

An entry in `rx.Config(plugins=[...])` is neither a Plugin instance nor a Plugin subclass — it is some other object entirely (a string import path, a module, an unrelated class).

Source

Thrown at packages/reflex-base/src/reflex_base/config.py:467

            elif isinstance(entry, Plugin):
                normalized.append(entry)
            elif isinstance(entry, type) and issubclass(entry, Plugin):
                try:
                    normalized.append(entry())
                except TypeError as exc:
                    msg = (
                        f"reflex.Config.plugins entry {entry.__name__!r} could not be "
                        f"instantiated and may require arguments; pass an instance "
                        f"instead, e.g. plugins=[{entry.__name__}(...)]."
                    )
                    raise InvalidPluginConfigError(msg) from exc
            else:
                msg = (
                    f"reflex.Config.plugins must contain Plugin instances, but got "
                    f"{entry!r} of type {type(entry).__name__}. "
                    f"Pass an instance, e.g. plugins=[SitemapPlugin()]."
                )
                raise InvalidPluginConfigError(msg)
        if invalid:
            details = ", ".join(p.describe() for p in invalid)
            msg = (
                f"reflex.Config.plugins contains plugin(s) that could not be loaded "
                f"(check REFLEX_PLUGINS import paths): {details}."
            )
            raise InvalidPluginConfigError(msg)
        self.plugins = normalized

    def _add_extra_plugins(self):
        """Append plugins declared via the ``REFLEX_EXTRA_PLUGINS`` env var.

        Unlike ``REFLEX_PLUGINS``, which *replaces* ``plugins`` entirely, this env
        var appends to the existing list so plugins configured in ``rxconfig.py``
        are preserved. Each entry is a fully qualified import path resolved to a
        Plugin *subclass* (not instantiated by the env machinery). For each class:

        - An invalid import path is warned about and skipped (a bad env entry is

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Import the plugin and pass an instance: `plugins=[SitemapPlugin()]`
2. For string import paths, use the REFLEX_PLUGINS environment variable instead

Example fix

# before
rx.Config(plugins=["myapp.plugins.SitemapPlugin"])

# after
from myapp.plugins import SitemapPlugin
rx.Config(plugins=[SitemapPlugin()])

from reflex_base.config import Plugin

def clean_plugins(entries):
    return [e for e in entries if isinstance(e, Plugin)]

from reflex_base.config import Plugin

def is_plugin_instance(v) -> bool:
    return isinstance(v, Plugin) and not isinstance(v, type)

When it happens

Trigger: `plugins=["myapp.plugins.SitemapPlugin"]` (string path is not accepted here) or `plugins=[SomeRandomClass]`.

Common situations: Expecting string-based plugin registration (that is what the `REFLEX_PLUGINS` env var is for) and putting paths directly in `plugins=[...]`.

Related errors

• reflex.Config.plugins entry {entry.__name__!r} could not be
• reflex.Config.plugins contains plugin(s) that could not be l
• {self._prefixes[0]}REDIS_URL is required when using the redi
• default_color_mode must be one of {allowed_color_modes}, but
• Invalid type for environment variable {field_name}: {field_t

AI-assisted analysis of reflex-dev/reflex@45b8ed5ab7 (2026-08-28). Data as JSON: /api/errors/fda342f0734914ad. Report an issue: GitHub.