@@ -15,9 +15,23 @@ The `frontend` errors are coming from the JavaScript side of the application, wh
 
 ### Frontend and backend state mismatches
 
-If a backend update names a substate that the compiled frontend does not recognize, Reflex skips that substate. Updates to known substates and subsequent events continue to work. Reflex warns in the browser console and reports each unknown substate to `frontend_exception_handler` once per connection.
+The compiled frontend and the backend can come from different builds of the app: a backend deploy changes the state while a browser keeps the old page, two backend versions run behind one load balancer during a rolling deploy, or `api_url` points at a backend that did not serve the frontend. The frontend then holds states, vars and event handlers the backend does not know, or the other way around.
 
-This can happen when a backend deploy adds state while a browser still uses an older frontend bundle. Refresh the page to load the matching bundle. If the warning persists, rebuild the frontend and check that `api_url` points to the intended backend. Reflex only skips unknown substates; it does not reconcile other differences, such as a renamed state or a changed var.
+Reflex detects this when the frontend connects. The compiled frontend carries a hash of the state tree it was built for (the state names, their frontend vars with types, and their event handler names) and sends it with every socket connect and reconnect. The backend computes the same hash over its own state tree and compares the two. Defaults and values are not part of the hash, so changing a default value does not count as a mismatch.
+
+On a mismatch:
+
+- In production, the page reloads once to fetch the new frontend. The reload shares the `REFLEX_AUTO_RELOAD_COOLDOWN` (default 10 seconds) with the automatic reload on frontend errors, so a page never reloads in a loop. When a reload already happened inside the cooldown (the reload landed on the same mismatch, for example a cached page or mixed backend versions) the page shows a banner saying a new version of the app is available, with a reload button, and keeps working as well as it can.
+- In development, the frontend only logs a warning in the browser console. A backend hot reload can reconnect before the frontend dev server serves the rebuilt page, which gives a short-lived mismatch that resolves on its own.
+
+The backend logs one warning per mismatched connection.
+
+Independently of that check, if a backend update names a substate that the compiled frontend does not recognize, Reflex skips that substate. Updates to known substates and subsequent events continue to work. Reflex warns in the browser console and reports each unknown substate to `frontend_exception_handler` once per connection. If the warning persists after a reload, rebuild the frontend and check that `api_url` points to the intended backend. Reflex only skips unknown substates; it does not reconcile other differences, such as a renamed state or a changed var.
+
+```md alert warning
+# Load balancers need sticky sessions.
+When several backend versions run behind one load balancer, each reconnect can land on a different version, and the frontend cannot match all of them. Pin each client to one backend (sticky sessions) or to one deployment during a rollout; the framework cannot work around this.
+```
 
 ## Register an Exception Handler
 
 
@@ -0,0 +1 @@
+Detect a frontend built for another version of the app when it connects to the backend. The compiled frontend now carries a hash of the state tree (state names, frontend vars and event handler names) and sends it on every socket connect. On a mismatch, a production page reloads once (sharing the `REFLEX_AUTO_RELOAD_COOLDOWN` with the reload on frontend errors) and otherwise shows a "new version available" banner with a reload button; in dev mode it only logs a console warning. Load balancers serving several backend versions still need sticky sessions.
@@ -0,0 +1 @@
+The compiled context module exports `stateSchema`, a hash of the state tree the frontend was built for, and the frontend sends it in the socket.io CONNECT `auth` payload under the `state_schema` key. The backend answers a mismatch with the new `state_mismatch` socket event; in production, the frontend then reloads once per cooldown window or shows a "new version available" banner, while in development it only warns in the console.
@@ -22,6 +22,15 @@ const EVENTURL = env.EVENT;
 
 // Socket event names (must match reflex_base/constants/event.py SocketEvent)
 const CLIENT_ERROR_EVENT = "client_error";
+const STATE_MISMATCH_EVENT = "state_mismatch";
+
+// sessionStorage key with the time of the last automatic reload (must match
+// LAST_RELOADED_KEY in reflex/state.py: the reload on a frontend error and the
+// reload on a state mismatch share one cooldown, so neither can loop).
+const LAST_RELOADED_KEY = "reflex_last_reloaded_on_error";
+
+// The id of the banner offering a reload when one already happened recently.
+const NEW_VERSION_BANNER_ID = "reflex-new-version-banner";
 
 // Client error types (must match reflex_base/constants/event.py ClientErrorType)
 const ERROR_TYPE_DISPATCH_MISSING = "dispatch_function_missing";
@@ -792,6 +801,74 @@ export const processEvent = async (socket, navigate, params) => {
   }
 };
 
+/**
+ * Reload the page for a new version of the app, restarting the reload cooldown.
+ */
+const reloadForNewVersion = () => {
+  window.sessionStorage.setItem(LAST_RELOADED_KEY, Date.now().toString());
+  window.location.reload();
+};
+
+/**
+ * Show a banner saying a new version is available, with a reload button.
+ *
+ * Plain DOM rather than a React component: it must show whatever the app
+ * renders, and stay up while the page keeps working as well as it can.
+ */
+const showNewVersionBanner = () => {
+  if (document.getElementById(NEW_VERSION_BANNER_ID)) {
+    return;
+  }
+  const banner = document.createElement("div");
+  banner.id = NEW_VERSION_BANNER_ID;
+  banner.setAttribute("role", "alert");
+  banner.style.cssText =
+    "position:fixed;top:0;left:0;right:0;z-index:2147483647;display:flex;" +
+    "justify-content:center;align-items:center;gap:1rem;padding:0.5rem 1rem;" +
+    "background:#1c2024;color:#fff;font:1rem system-ui,sans-serif;";
+  banner.append("A new version of this app is available.");
+  const button = document.createElement("button");
+  button.textContent = "Reload";
+  button.style.cssText =
+    "padding:0.25rem 0.75rem;border:1px solid #fff;border-radius:4px;" +
+    "background:transparent;color:inherit;font:inherit;cursor:pointer;";
+  button.onclick = reloadForNewVersion;
+  banner.append(button);
+  document.body.append(banner);
+};
+
+/**
+ * Handle the backend reporting that this bundle was compiled for another
+ * state tree than the one it runs (sent on connect, see EventNamespace.on_connect).
+ *
+ * In prod the page reloads once per cooldown window. A mismatch inside the
+ * window means the reload landed on the same skew (a cached bundle, or several
+ * backend versions behind one load balancer), so a banner with a reload button
+ * shows instead and the page never loops. In dev a backend hot reload can
+ * reconnect before Vite serves the rebuilt bundle, so it only warns.
+ * @param info The backend's state schema hash and the reload cooldown in ms.
+ */
+const handleStateMismatch = (info) => {
+  const message =
+    "This page was built for another version of the app than the backend it " +
+    `connected to (state schema ${app.stateSchema}, backend ${info.backend}).`;
+  if (app.isDevMode) {
+    console.warn(
+      message +
+        " Reload the page if it stays out of date once the frontend rebuilds.",
+    );
+    return;
+  }
+  const last_reload =
+    parseInt(window.sessionStorage.getItem(LAST_RELOADED_KEY)) || 0;
+  if (Date.now() - last_reload > info.reload_cooldown_ms) {
+    reloadForNewVersion();
+    return;
+  }
+  console.warn(message + " Reload the page to get the new version.");
+  showNewVersionBanner();
+};
+
 /**
  * Connect to a websocket and set the handlers.
  * @param socket The socket object to connect.
@@ -824,14 +901,16 @@ export const connect = async (
 
   // The hydrate event rides in the socket.io CONNECT packet, so the backend
   // starts loading state as soon as the namespace connects instead of after
-  // an extra round trip for the connect acknowledgement. The key is read by
-  // the backend as CompileVars.CONNECT_AUTH_EVENT.
+  // an extra round trip for the connect acknowledgement. The keys are read by
+  // the backend as CompileVars.CONNECT_AUTH_EVENT and CONNECT_AUTH_STATE_SCHEMA;
+  // the state schema goes along on every (re)connect, since a reconnect can
+  // land on another backend version.
   const bootAuth = (first) => {
     const boot_event = withRouterData(app.initialEvents(first)[0], params);
     recordSentStorageValues(boot_event);
     // Instrumentation hook (installed by reflex-otel): may add a traceparent.
     window.__reflex_otel?.onEventSend?.(boot_event);
-    return { event: boot_event };
+    return { event: boot_event, state_schema: app.stateSchema };
   };
 
   // Create the socket. A new session's token is saved here, once the app has
@@ -1041,6 +1120,7 @@ export const connect = async (
     token = new_token;
     window.sessionStorage.setItem(TOKEN_KEY, new_token);
   });
+  socket.current.on(STATE_MISMATCH_EVENT, handleStateMismatch);
 
   document.addEventListener("visibilitychange", checkVisibility);
   socket.current.connect();
 
@@ -313,6 +313,7 @@ def context_template(
     initial_state_json: str | None = None,
     initial_state_hashes: list[str] | None = None,
     state_name: str | None = None,
+    state_schema: str | None = None,
     client_storage: dict[str, dict[str, dict[str, Any]]] | None = None,
     disable_react_owner_stacks: bool = False,
 ):
@@ -325,6 +326,10 @@ def context_template(
             state name order, sent with the first hydrate so the backend can
             skip vars still at their default.
         state_name: The name of the state.
+        state_schema: Hash of the state tree (names, frontend vars, event
+            handlers) this frontend is compiled for, sent on every socket
+            connect so the backend can detect a frontend built for another
+            version of the app.
         client_storage: The client storage for the context.
         is_dev_mode: Whether the app is in development mode.
         default_color_mode: The default color mode for the context.
@@ -452,6 +457,7 @@ def context_template(
 export {{ ColorModeContext, UploadFilesContext, DispatchContext, EventLoopContext }};
 export const initialState = {initial_state_json}
 export const initialStateHashes = {"[]" if not initial_state_hashes else json_dumps(initial_state_hashes)}
+export const stateSchema = {json.dumps(state_schema)}
 
 export const defaultColorMode = {default_color_mode}
 export const StateContexts = {{{state_contexts_str}}};
@@ -467,6 +473,7 @@ def context_template(
   initialState,
   clientStorage,
   state_name,
+  stateSchema,
   exception_state_name,
   onLoadInternalEvent,
   initialEvents,
 
@@ -61,6 +61,9 @@ class CompileVars(SimpleNamespace):
     HYDRATE_AND_LOAD = "hydrate_and_load"
     # The key of the socket.io CONNECT auth packet that carries the boot event.
     CONNECT_AUTH_EVENT = "event"
+    # The key of the CONNECT auth packet that carries the hash of the state
+    # tree the frontend was compiled for; an old frontend sends none.
+    CONNECT_AUTH_STATE_SCHEMA = "state_schema"
     # Payload keys of hydrate_and_load / update_vars_internal; they are passed
     # through as handler kwargs, so they must match those parameter names.
     PAYLOAD_VARS = "vars"
 
@@ -50,6 +50,9 @@ class SocketEvent(SimpleNamespace):
     PING = "ping"
     EVENT = "event"
     CLIENT_ERROR = "client_error"
+    # Sent on connect when the frontend was compiled for another state tree
+    # (must match STATE_MISMATCH_EVENT in .templates/web/utils/state.js).
+    STATE_MISMATCH = "state_mismatch"
 
     def __str__(self) -> str:
         """Get the string representation of the event name.
 
@@ -28,6 +28,7 @@
     Sequence,
 )
 from contextvars import Token
+from datetime import timedelta
 from pathlib import Path
 from types import SimpleNamespace
 from typing import TYPE_CHECKING, Any, overload
@@ -2167,11 +2168,35 @@ async def on_connect(self, sid: str, environ: dict, auth: Any = None):
         if isinstance(self._token_manager, RedisTokenManager):
             # Make sure this instance is watching for updates from other instances.
             self._token_manager.ensure_lost_and_found_task(self.emit_update)
-        boot_event = (
-            auth.get(constants.CompileVars.CONNECT_AUTH_EVENT)
-            if isinstance(auth, dict)
-            else None
-        )
+        boot_event = frontend_schema = None
+        if isinstance(auth, dict):
+            boot_event = auth.get(constants.CompileVars.CONNECT_AUTH_EVENT)
+            frontend_schema = auth.get(constants.CompileVars.CONNECT_AUTH_STATE_SCHEMA)
+        # A frontend compiled for another state tree is told so before it
+        # hydrates; an older frontend sends no hash and is left alone. The
+        # backend hash is cached on the state class, so this is one lookup.
+        if (
+            frontend_schema is not None
+            and self.app._state is not None
+            and frontend_schema
+            != (backend_schema := self.app._state._to_frontend_schema())
+        ):
+            logger.warning(
+                "Frontend state schema "
+                f"{format.sanitize_client_log_value(frontend_schema, max_length=64)} "
+                f"for session {sid} does not match the backend state schema "
+                f"{backend_schema}: the frontend was built for another version of "
+                "the app and is told to reload."
+            )
+            await self.emit(
+                str(constants.SocketEvent.STATE_MISMATCH),
+                {
+                    "backend": backend_schema,
+                    "reload_cooldown_ms": auto_reload_cooldown()
+                    // timedelta(milliseconds=1),
+                },
+                to=sid,
+            )
         query_params = urllib.parse.parse_qs(environ.get("QUERY_STRING", ""))
         token_list = query_params.get("token", [])
         if token_list:
 
@@ -272,6 +272,7 @@ def _compile_contexts(
             initial_state_json=initial_state_json,
             initial_state_hashes=state_snapshot_hashes(initial_state),
             state_name=state.get_name(),
+            state_schema=state._to_frontend_schema(),
             client_storage=utils.compile_client_storage(state),
             is_dev_mode=not is_prod_mode(),
             default_color_mode=default_color_mode,
 
@@ -8,7 +8,9 @@
 import functools
 import hashlib
 import inspect
+import json
 import logging
+import operator
 import pickle
 import re
 import sys
@@ -1105,8 +1107,10 @@ def _init_var_dependency_dicts(cls):
                     parent_state.get_parent_state(),
                 )
 
-        # Reset cached schema value
+        # Reset cached schema values; the frontend schema spans the tree, so a
+        # change to any state invalidates every cached root.
         cls._to_schema.cache_clear()
+        _frontend_schema.cache_clear()
 
     @classmethod
     def _iter_functions(cls) -> Iterator[tuple[str, FunctionType]]:
@@ -2152,6 +2156,22 @@ def _field_tuple(
             )
         ).hexdigest()
 
+    @classmethod
+    def _to_frontend_schema(cls) -> str:
+        """Hash what a compiled frontend depends on, over the whole state tree.
+
+        For each state below (and including) this one: its full name, the
+        names and types of its frontend vars (base and computed), and its
+        event handler names. Defaults and values are left out, so a frontend
+        compiled from one tree matches a backend running another exactly when
+        the two trees are compatible. The compiler writes this hash into the
+        frontend and the backend compares it on each socket connect.
+
+        Returns:
+            The hash of the frontend schema.
+        """
+        return _frontend_schema(cls, RegistrationContext.get())
+
     def _serialize(self) -> bytes:
         """Serialize the state for redis.
 
@@ -2246,6 +2266,48 @@ def _deserialize(
         return state
 
 
+@functools.lru_cache
+def _frontend_schema(root: type[BaseState], context: RegistrationContext) -> str:
+    """Hash the frontend schema of the state tree below ``root``.
+
+    The tree is read from ``context``, which is part of the cache key: apps in
+    one process run on forked registration contexts that share the root class
+    but not its substates. ``BaseState._init_var_dependency_dicts`` clears the
+    cache whenever a state is added or changed.
+
+    Args:
+        root: The state at the top of the tree.
+        context: The registration context holding the tree.
+
+    Returns:
+        The hash of the frontend schema.
+    """
+
+    def _state_entry(state: type[BaseState]) -> list[Any]:
+        fields = state.get_fields()
+        return [
+            state.get_full_name(),
+            sorted(
+                (name, _serialize_type(fields[name].type_)) for name in state.base_vars
+            ),
+            sorted(
+                (name, _serialize_type(cvar._var_type))
+                for name, cvar in state.computed_vars.items()
+                if not cvar._backend
+            ),
+            sorted(state.event_handlers),
+        ]
+
+    entries = []
+    pending = [root]
+    while pending:
+        state = pending.pop()
+        entries.append(_state_entry(state))
+        pending.extend(context.get_substates(state))
+    entries.sort(key=operator.itemgetter(0))
+    return md5(json.dumps(entries, separators=(",", ":")).encode("utf-8")).hexdigest()
+
+
 def _legacy_state_schema(state_cls: type[BaseState]) -> str:
     """Hash the previous schema format to restore compatible persisted states.
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Detect a frontend built for another version of the app when it connects to the backend. The compiled frontend now carries a hash of the state tree (state names, frontend vars and event handler names) and sends it on every socket connect. On a mismatch, a production page reloads once (sharing the `REFLEX_AUTO_RELOAD_COOLDOWN` with the reload on frontend errors) and otherwise shows a "new version available" banner with a reload button; in dev mode it only logs a console warning. Load balancers serving several backend versions still need sticky sessions.
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+The compiled context module exports `stateSchema`, a hash of the state tree the frontend was built for, and the frontend sends it in the socket.io CONNECT `auth` payload under the `state_schema` key. The backend answers a mismatch with the new `state_mismatch` socket event; in production, the frontend then reloads once per cooldown window or shows a "new version available" banner, while in development it only warns in the console.