reflex-dev/reflex · error · VarValueError

Cached var {self!s} cannot access arbitrary state `{instruct

Error message

Cached var {self!s} cannot access arbitrary state `{instruction.argval}`, is it defined yet?

What it means

During dependency tracking of a cached var, Reflex resolves names loaded from closures (LOAD_DEREF). If the closure cell for the referenced name is missing or not yet populated (KeyError/ValueError), Reflex cannot tell which state class is being accessed and raises VarValueError.

Source

Thrown at packages/reflex-base/src/reflex_base/vars/dep_tracking.py:283

            raise VarValueError(msg)
        if instruction.opname in ("LOAD_FAST", "LOAD_FAST_BORROW"):
            self._getting_state_class = self.get_tracked_local(
                local_name=instruction.argval,
            )
        elif instruction.opname == "LOAD_GLOBAL":
            # Special case: referencing state class from global scope.
            try:
                self._getting_state_class = self._get_globals()[instruction.argval]
            except (ValueError, KeyError) as ve:
                msg = f"Cached var {self!s} cannot access arbitrary state `{instruction.argval}`, not found in globals."
                raise VarValueError(msg) from ve
        elif instruction.opname == "LOAD_DEREF":
            # Special case: referencing state class from closure.
            try:
                self._getting_state_class = self._get_closure()[instruction.argval]
            except (ValueError, KeyError) as ve:
                msg = f"Cached var {self!s} cannot access arbitrary state `{instruction.argval}`, is it defined yet?"
                raise VarValueError(msg) from ve
        elif instruction.opname in ("LOAD_ATTR", "LOAD_METHOD"):
            self._getting_state_class = getattr(
                self._getting_state_class,
                instruction.argval,
            )
        elif instruction.opname == "GET_AWAITABLE":
            # Now inside the `await` machinery, subsequent instructions
            # operate on the result of the `get_state` call.
            self.scan_status = ScanStatus.GETTING_STATE_POST_AWAIT
            if self._getting_state_class is not None:
                self.top_of_stack = "_"
                self.tracked_locals[self.top_of_stack] = self._getting_state_class
                self._getting_state_class = None

    def handle_getting_state_post_await(self, instruction: dis.Instruction) -> None:
        """Handle bytecode analysis after `get_state` was called in the function.

        This function is called _after_ awaiting self.get_state to capture the

View on GitHub (pinned to 45b8ed5ab7)

Solutions

Move the definition of the closed-over name (state class) above the cached var that uses it.
Convert the closure reference into a direct module-level import so it resolves via LOAD_GLOBAL from globals.
If the name is defined conditionally, restructure so it is always defined before the cached var is declared.

Example fix

# before
@rx.var(cached=True)
def total(self) -> int:
    return self.v + LaterState.v  # LaterState defined below

class LaterState(rx.State):
    v: int = 0

# after
class LaterState(rx.State):
    v: int = 0

@rx.var(cached=True)
def total(self) -> int:
    return self.v + LaterState.v

Defensive patterns

Strategy: validation

Validate before calling

def closure_cell_defined(func, name: str) -> bool:
    if func.__closure__ is None:
        return False
    names = func.__code__.co_freevars
    return name in names and dict(zip(names, func.__closure__)).get(names.index(name)) is not None

Prevention

Define state classes before cached vars that reference them.
Prefer module-level imports over closure captures in cached vars.
Keep module definition order stable when refactoring.

When it happens

Trigger: A cached var function closes over a name (e.g. a state class defined later in the same module, or a closure variable that is unbound at scan time) and references it like `ClosedState.value`. The name is not yet in the function's closure when Reflex inspects the bytecode.

Common situations: Defining a state class after the cached var that references it inside the same module; late-binding closures; partial functions or decorators that capture names defined conditionally; module reload/dynamic definition ordering issues.

Related errors

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