reflex-dev/reflex · error · ValueError

Alpha must be a boolean or a Var

Error message

Alpha must be a boolean or a Var

What it means

The `alpha` parameter of `rx.color()` must be a boolean or a Var. It toggles whether the returned color uses the alpha (opacity) variant of the theme color; numeric opacity values are not supported.

Source

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

    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. Pass True/False: rx.color('red', 7, True)
2. For fractional opacity, wrap the result: rx.box(opacity=0.5, background=rx.color('red', 7))
3. For dynamic alpha, pass a Var of bool type

Example fix

// before
rx.color('red', 7, 0.5)
// after
rx.box(background=rx.color('red', 7), opacity=0.5)

alpha = bool(alpha) if not isinstance(alpha, Var) else alpha

def is_valid_alpha(a) -> bool:
    return isinstance(a, (bool, Var))

When it happens

Trigger: `rx.color('red', 7, 0.5)`, `rx.color('red', 7, 1)`, or passing an alpha string 'true'.

Common situations: Assuming alpha is an opacity float like in CSS rgba(); migrating from styles that used opacity numbers.

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

• Color must be a string or a Var
• Shade must be an integer 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/98b93a2ec0a9f850. Report an issue: GitHub.