Raise a clear error when a hybrid property reads a backend var on a state

[masenf]

Type of change

• New feature (non-breaking change which adds functionality)

Note

Stacked on #6619 — base branch is claude/relaxed-cerf-Z110q. This PR contains only the backend-var guard; review it against that base.

Description

A hybrid property's frontend logic (its getter, or a custom @<name>.var function) runs with the state class as self when building the frontend var. Reading a backend (underscore-prefixed) var there previously baked the var's class-level default into the frontend as a frozen literal — a silent leak that never updates and is not reactive.

This PR makes that misuse fail loudly with a clear, actionable error.

Changes:

1. HybridProperty._get_var guards the state owner (packages/reflex-base/src/reflex_base/vars/hybrid_property.py): when a hybrid property is resolved against a BaseState, the owner is wrapped in a _StateBackendVarGuard. Accessing a backend var while building the frontend var raises, with the traceback pointing at the offending line in the user's getter/.var function. Object-var owners (nested dataclass / pydantic / SQLAlchemy access) have no backend vars and are passed through unchanged.

2. New HybridPropertyError (packages/reflex-base/src/reflex_base/utils/exceptions.py): a dedicated ReflexError — deliberately not an AttributeError, so it can't be silently swallowed by getattr(..., default) / hasattr — whose message names the property, the state, and the offending backend var, and suggests using a regular var or a separate @<name>.var implementation.

Tests

tests/units/vars/test_hybrid_property.py:

• backend-var access raises HybridPropertyError from both the getter and a custom .var function
• frontend-only logic still builds the expected var
• the guard is state-only — underscore fields accessed through an object var are unaffected

https://claude.ai/code/session_01DKFiYGnWRQG8wMNKFW7obm

[codspeed-hq]

Merging this PR will not alter performance

✅ 26 untouched benchmarks
⏩ 8 skipped benchmarks¹

---

_{Comparing claude/hybrid-property-backend-var-guard (7b40b13) with main (e059363)}

Footnotes

1. 8 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[greptile-apps]

Greptile Summary

This PR adds a guard that raises a clear HybridPropertyError when a hybrid property's frontend logic (its getter or custom .var function) reads a backend (underscore-prefixed) state var, converting a previously silent data-leak into a loud, actionable error. It also fixes the var() method to return a new descriptor instance rather than mutating the existing one, preventing descriptor sharing across mixin subclasses.

• _StateBackendVarGuard wraps the state class when building the frontend var and intercepts __getattr__ to block any attribute that's in state_cls.backend_vars (which already includes inherited backend vars via {**inherited_backend_vars, **new_backend_vars}), so the inheritance case is handled correctly.
• HybridPropertyError is a ReflexError (not AttributeError) so it can't be silently swallowed by hasattr/getattr with a default; the error message names the property, the state, and the offending var.
• Tests cover backend-var access from both the getter and the .var function, frontend-only access, mixin descriptor isolation, and the object-var pass-through (guard is state-only).

Confidence Score: 5/5

Safe to merge — the guard is narrowly scoped to BaseState subclasses, backend_vars correctly includes inherited vars so the optimization path is sound, and no existing behavior is changed for states with no backend vars or for object-var access.

The change is well-contained: a new private proxy class, one new exception, and a narrowly conditional branch in get. The core invariant — that backend_vars already aggregates inherited backend vars — is confirmed in the state metaclass. No breaking changes, and the test suite directly exercises the four meaningful cases.

No files require special attention.

Important Files Changed

Filename	Overview
packages/reflex-base/src/reflex_base/vars/hybrid_property.py	Adds _StateBackendVarGuard proxy and updates get to wrap state owners, plus fixes var() to return a new descriptor instance; logic is correct and well-structured.
packages/reflex-base/src/reflex_base/utils/exceptions.py	Adds HybridPropertyError as a dedicated ReflexError subclass; correctly not an AttributeError to prevent silent swallowing by hasattr/getattr.
tests/units/vars/test_hybrid_property.py	New test file covering backend-var access from getter and .var function, frontend-only access, mixin descriptor isolation, and object-var pass-through; all scenarios are well-targeted.
news/6621.feature.md	Changelog entry for the root package; clear user-facing description of the new error behavior.
packages/reflex-base/news/6621.feature.md	Changelog entry for the reflex-base package; accurately describes HybridPropertyError addition.

_{Reviews (5): Last reviewed commit: "fix(hybrid_property): return new descrip..." | Re-trigger Greptile}