Diagnosing Lost UI State in Vaadin Flow After Client‑Side Navigation

Recognizable Condition

After a client‑side navigation (e.g., a RouterLink click), the page shows the correct view, but the component values that were set on the server side (e.g., a TextField value or a Grid selection) are missing or reset. The Java model remains unchanged, but the DOM does not reflect it.

Primary Cause

The server‑side UI state synchronization that normally runs during a navigation request is skipped because the client‑side router performs the navigation without a full HTTP round‑trip. The ClientConnector#enter hook that pushes the updated state to the browser is not invoked, leaving the client view stale.

Diagnostic Table

Check	What to look for	Result indicates
1 – Router registration	Target view annotated with @Route	Missing: server never receives navigation request
2 – Browser console	vaadin:// WebSocket messages, no JS errors	Missing messages: broken sync channel
3 – Server log	UIState sync entry after navigation	Absent: state not pushed

Ordered Checks

1. Verify @Route Annotation
   Ensure every view that can be navigated to from the client side has a @Route("path") annotation. If a view is missing this, Vaadin’s server‑side router never processes the navigation, so no state sync occurs.

   import com.vaadin.flow.router.Route;
   @Route("dashboard")
   public class DashboardView extends VerticalLayout { ... }
   

2. Inspect Browser Console
   Open DevTools (F12) and check for errors. Look for messages like:

   vaadin://sync: failed to send state delta

   If you see a WebSocket error or a missing vaadin:// message, the client cannot reach the server.
3. Check Server Side Logging
   Add a simple debug listener to capture UI state sync events:

   UI.getCurrent().addUIInitListener(ui ->
         ui.getPage().executeJs("console.log('UI initialized')"));
   

   After a client‑side navigation, look for a log entry similar to:

   UIState: pushing 3 connectors

   If absent, the sync hook was not called.
4. Validate WebSocket Connection
   In the Network tab, filter by WebSocket and confirm the vaadin:// channel is open and exchanging frames. A closed or error‑state socket prevents state pushes.

Fixes Tied to Findings

• Missing @Route
  Add the annotation to the view class. This ensures the server processes navigation and triggers ClientConnector#enter.
• Broken WebSocket
  Verify that the application is served from the same origin and that firewalls or proxies allow WebSocket traffic. If necessary, configure the server to use a vaadin:// fallback or enable vaadin.disableWebSocket to force HTTP polling.
• State Sync Not Triggered
  Force a manual sync after a client‑side navigation by adding a listener in onAttach of the view:

  @Override
    public void onAttach(AttachEvent attachEvent) {
        // Force a full state push
        UI.getCurrent().getPage().executeJs(
            "window.vaadinApi.updateState()"
        );
    }
  

• Preserve Router State
  On recent Vaadin versions, the router can preserve UI state across client‑side navigation:

  Router router = UI.getCurrent().getRouter();
  router.setPreserveState(true);
  

  This tells the router to keep the server UI alive and push any pending state changes.

Escalation Criteria

If after applying the above fixes the UI state still does not appear, consider:

• Custom ClientConnector subclasses that override onStateChanged without calling super.
• Third‑party add‑ons that modify the Vaadin client bundle or interfere with the WebSocket layer.
• High‑traffic production environments where frequent enter calls may overload the server; in this case, enable vaadin.debug to throttle syncs.

Gather the following before raising a ticket:

• Server console logs showing the absence of UIState sync entries.
• Browser console with WebSocket frames and any error messages.
• Configuration files (e.g., application.properties) showing router settings.

Verification Checklist

1. Open the app in a browser and navigate to a view via RouterLink.
2. Set a value on a component in the target view.
3. Navigate away using another RouterLink and return.
4. Confirm the component still shows the value set earlier.
5. Check the server log for a line like UIState: pushing… after the return navigation.
6. In the browser console, see a vaadin:// message indicating a state delta was sent.

Limitations & Practical Notes

• Forcing a full state sync on every navigation can increase server load; use sparingly in high‑traffic apps.
• Enabling router.setPreserveState(true) may interfere with deep‑link handling; test all navigation paths before production.
• Custom ClientConnector implementations must call super.onStateChanged() to avoid breaking the sync chain.
• Some proxies strip WebSocket headers; ensure Upgrade and Connection headers are preserved.

Conclusion

Loss of UI state after client‑side navigation in Vaadin Flow usually stems from a missing @Route annotation, a broken WebSocket channel, or an overridden sync hook. By following the ordered checks, applying the targeted fixes, and verifying the state sync, you can restore consistent UI behavior across all navigation paths.