reflex-dev/reflex · error · ValueError

Color must be a string or a Var

Error message

Color must be a string or a Var

What it means

`rx.color()` only accepts a `str` (a palette color name) or a `Var`. Passing any other type (int, list, dict, None, tuple) fails this isinstance check before any color resolution happens.

Source

Thrown at packages/reflex-components-core/src/reflex_components_core/core/colors.py:39

    Args:
        color: The color to use.
        shade: The shade of the color to use.
        alpha: Whether to use the alpha variant of the color.

    Returns:
        The color object.

    Raises:
        ValueError: If the color, shade, or alpha are not valid.
    """
    if isinstance(color, str):
        if color not in COLORS and REFLEX_VAR_OPENING_TAG not in color:
            msg = f"Color must be one of {COLORS}, received {color}"
            raise ValueError(msg)
    elif not isinstance(color, Var):
        msg = "Color must be a string or a Var"
        raise ValueError(msg)

    if isinstance(shade, int):
        if shade < MIN_SHADE_VALUE or shade > MAX_SHADE_VALUE:
            msg = f"Shade must be between {MIN_SHADE_VALUE} and {MAX_SHADE_VALUE}"
            raise ValueError(msg)
    elif not isinstance(shade, Var):
        msg = "Shade must be an integer or a Var"
        raise ValueError(msg)

    if not isinstance(alpha, (bool, Var)):
        msg = "Alpha must be a boolean or a Var"
        raise ValueError(msg)

    return Color(color, shade, alpha)

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Ensure the first argument is a str color name or a Var
2. If the value may be None, provide a fallback: rx.color(color or 'red')
3. Convert non-string values to str before calling, if they actually hold a palette name

Example fix

// before
rx.color(some_config.get('color'))  # may be None or int
// after
rx.color(str(some_config.get('color', 'red')))

def safe_color(c, default='red'):
    if c is None:
        return default
    return c if isinstance(c, (str, Var)) else str(c)

def is_color_arg(c) -> bool:
    return isinstance(c, (str, Var))

When it happens

Trigger: `rx.color(None)`, `rx.color(7)`, `rx.color(['red'])`, or a value read from untyped config data that isn't a string or Var.

Common situations: Passing a shade number as the first argument by mistake; forwarding values from user input or JSON config without converting to str; defaulting a parameter to None and forwarding it into rx.color().

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

• Shade must be an integer or a Var
• Alpha must be a boolean or a Var
• Invalid data type {type(data)} for download. Use `str` or `b
• Cannot serialize color that contains non-literal vars.
• Color is not a valid color.

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