reflex-dev/reflex · error · ValueError

prop value for {key!s} of the `{comp_name}` component should

Error message

prop value for {key!s} of the `{comp_name}` component should be one of the following: {allowed_value_str}. Got {value_str} instead

What it means

This ValueError is raised by reflex-base's validate_literal when a component prop is annotated with typing.Literal[...] but the value passed is not one of the allowed members. The message lists the permitted values for the given component and prop key, plus the offending value. It exists to catch invalid prop values at Python time instead of silently generating broken JavaScript.

Source

Thrown at packages/reflex-base/src/reflex_base/utils/types.py:1141

    Raises:
        ValueError: When the value is not a valid literal.
    """
    from reflex_base.vars import Var

    if (
        is_literal(expected_type)
        and not isinstance(value, Var)  # validating vars is not supported yet.
        and not is_encoded_fstring(value)  # f-strings are not supported.
        and value not in expected_type.__args__
    ):
        allowed_values = expected_type.__args__
        if value not in allowed_values:
            allowed_value_str = ",".join([
                str(v) if not isinstance(v, str) else f"'{v}'" for v in allowed_values
            ])
            value_str = f"'{value}'" if isinstance(value, str) else value
            msg = f"prop value for {key!s} of the `{comp_name}` component should be one of the following: {allowed_value_str}. Got {value_str} instead"
            raise ValueError(msg)


def safe_issubclass(cls: Any, cls_check: Any | tuple[Any, ...]):
    """Check if a class is a subclass of another class. Returns False if internal error occurs.

    Args:
        cls: The class to check.
        cls_check: The class to check against.

    Returns:
        Whether the class is a subclass of the other class.
    """
    try:
        return issubclass(cls, cls_check)
    except TypeError:
        return False

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Check the error message: it lists every allowed value — change the passed value to one of them
2. If the value comes from a variable, print/assert its runtime value before passing it to the component
3. If you upgraded reflex, check the changelog for the prop's Literal set changes and migrate the value
4. If you genuinely need an unlisted value, use the raw HTML escape hatch (rx.el or custom_component) or open an issue/PR to extend the Literal

Example fix

# before
rx.el.img(src='/x.png', loading='egar')
# after
rx.el.img(src='/x.png', loading='lazy')

from typing import get_args, get_type_hints
ALLOWED = get_args(get_type_hints(rx.el.img)['loading'])
assert loading in ALLOWED, f'loading must be one of {ALLOWED}'

def is_valid_literal(value: object, allowed: tuple) -> bool:
    return value in allowed

When it happens

Trigger: Passing a value outside a Literal-annotated prop's allowed set, e.g. rx.el.img(loading='egar') instead of 'eager'/'lazy', or an integer where the Literal expects a specific string. Any rx component whose prop is Literal-typed and receives a typo'd or wrong-typed value triggers this during rendering/compilation.

Common situations: Typos in prop names/values copied from docs; upgrading reflex where a prop's Literal set changed (a previously valid value removed); dynamically computed prop values that return unexpected types (e.g. numpy str instead of str); AI-generated or hand-written component wrappers passing unvalidated kwargs.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Only one default import is allowed.
• ChildrenTypeError(component=cls.__name__, child=child)
• Do not override _add_style directly. Use add_style instead.
• The component `{comp_name}` cannot have `{child_name}` as a
• The component `{comp_name}` only allows the components: {val

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