reflex-dev/reflex · error · EnvironmentVarValueError

Invalid literal value

Error message

Invalid literal value: {value!r} for {field_name}, expected one of {literal_values}

What it means

For Literal-typed fields the raw string (and, for int literals, its int() interpretation) must equal one of the Literal's values; otherwise EnvironmentVarValueError is raised listing the allowed values. This is strict equality validation, not fuzzy matching.

Solutions

1. Use exactly one of the values shown in the message
2. For int literals, pass a bare integer string
3. Check the field's Literal definition if unsure of allowed values

Example fix

# before
ENV=production  # Literal['dev','prod','test']
# after
ENV=prod

import typing
allowed = typing.get_args(LiteralType)
assert raw in allowed or (any(isinstance(a, int) for a in allowed) and raw.lstrip("+-").isdigit() and int(raw) in allowed), f"must be one of {allowed}"

def is_valid_literal(v: str, literal_vals: tuple) -> bool:
    return v in literal_vals or (v.lstrip("+-").isdigit() and int(v) in literal_vals)

except EnvironmentVarValueError:
    raw = allowed[0]  # first literal as fallback

When it happens

Trigger: Setting a Literal['dev','prod','test'] field to 'production', or a Literal[80, 443] field to '8080'. The code tries the string directly, then int-parses for int literals before failing.

Common situations: Env value drift from the allowed set ('production' vs 'prod'), numeric literals passed with units, or new allowed values not present in the pinned Reflex version.

Related errors

• Could not interpret for as any of
• Invalid boolean value
• Invalid enum value: for
• Invalid float value: for
• Invalid integer value

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

Appendix: source

Thrown at packages/reflex-base/src/reflex_base/environment.py:368

        for literal_value in literal_values:
            if isinstance(literal_value, str) and literal_value == value:
                return literal_value
            if isinstance(literal_value, bool):
                try:
                    interpreted_bool = interpret_boolean_env(value, field_name)
                    if interpreted_bool == literal_value:
                        return interpreted_bool
                except EnvironmentVarValueError:
                    continue
            if isinstance(literal_value, int):
                try:
                    interpreted_int = interpret_int_env(value, field_name)
                    if interpreted_int == literal_value:
                        return interpreted_int
                except EnvironmentVarValueError:
                    continue
        msg = f"Invalid literal value: {value!r} for {field_name}, expected one of {literal_values}"
        raise EnvironmentVarValueError(msg)
    # If the field was Annotated with SequenceOptions, extract the options
    sequence_options = DEFAULT_SEQUENCE_OPTIONS
    for arg in annotated_metadata:
        if isinstance(arg, SequenceOptions):
            sequence_options = arg
            break
    if get_origin(field_type) in (list, Sequence):
        items = value.split(sequence_options.delimiter)
        if sequence_options.strip:
            items = [item.strip() for item in items]
        return [
            interpret_env_var_value(
                v,
                get_args(field_type)[0],
                f"{field_name}[{i}]",
            )
            for i, v in enumerate(items)
        ]

View on GitHub (pinned to 45b8ed5ab7)