Diagnosing Vaadin Push Issues: From Missing Annotation to WebSocket Fallback

Recognizable Condition

When Vaadin Push is enabled but the UI does not receive server‑initiated updates, the client may fall back to long‑polling, show delayed updates, or display no change at all.

Cause / Diagnostic Table

Possible Cause	Symptom
@Push missing or on wrong class	No WebSocket upgrade request; console shows polling requests.
vaadin‑push dependency absent	Application starts but Push annotation is ignored; same polling behavior.
Servlet container lacks WebSocket support (e.g., Tomcat 8)	Framework logs fallback to long‑polling; ws:// handshake fails.
Browser does not support WebSocket (old IE)	Client uses XHR polling; increased network traffic.
Push message exceeds default 2 KB limit	Message fragmented or dropped; UI update missing or partial.
Non‑serializable UI component state	On reconnection, serialization exception in server logs; UI may reset.

Ordered Checks

1. Verify the UI class annotation
   1. Open the UI subclass source.
   2. Confirm it is annotated with @Push (or @Push(PushMode.AUTOMATIC)).
   3. Ensure the class extends com.vaadin.ui.UI (Vaadin 8) or com.vaadin.flow.component.UI (Flow).
2. Check Maven/Gradle dependency
   1. Look for vaadin-push in pom.xml or build.gradle.
   2. Version should match the Vaadin core version (e.g., 23.0.0).
3. Confirm servlet container WebSocket support
   1. For Tomcat, ensure version 9.0+; for Jetty, 9.4+.
   2. Check that the websocket module or ServletContainerInitializer is present (no extra config needed for embedded servers).
4. Inspect browser console for WebSocket handshake
   1. Open developer tools → Network → WS (or look for ws:// or wss:// requests).
   2. Successful handshake shows status 101 Switching Protocols.
   3. If only polling (GET ...?v-uiId) appears, WebSocket upgrade failed.
5. Test a manual push
   1. Add a temporary button that calls UI.getCurrent().access(() -> UI.getCurrent().push()); or use UI.getPage().push() from a background thread.
   2. Observe whether the client updates without a full reload.
6. Check push message size
   1. If you send large objects (e.g., big collections), enable Vaadin debug mode to see warnings about message size.
   2. Consider splitting data or using setData on components.
7. Verify component state serializability
   1. Look for java.io.NotSerializableException in server logs after a reconnection.
   2. Mark non‑serializable fields as transient or make them implement Serializable.

Fixes Tied to Findings

• Missing @Push → add the annotation to the UI subclass.
• Missing dependency → add <dependency><groupId>com.vaadin</groupId><artifactId>vaadin-push</artifactId><version>${vaadin.version}</version></dependency> (Maven) or equivalent Gradle.
• Unsupported container → upgrade to Tomcat 9+ or Jetty 9.4+, or enable WebSocket support via container‑specific configuration.
• Browser lack of WebSocket → inform users to use a modern browser; the framework will automatically fall back to polling, accepting higher latency.
• Message size > 2 KB → split updates, use push() with smaller payloads, or increase the buffer via vaadin.push.websocket.maxMessageSize if the container allows.
• Non‑serializable state → make fields transient or implement Serializable; review custom components for proper serialization.

Escalation Criteria

If after performing all checks the UI still does not receive updates:

• Enable Vaadin debug mode (vaadin.debug=true) and examine the console for detailed Push‑related logs.
• Capture a network trace (e.g., using Chrome DevTools) to confirm whether any WebSocket frames are being sent from server to client.
• Review server‑side logs for exceptions during PushHandler processing.
• If the problem persists, consider opening a Vaadin ticket with the gathered logs, dependency tree, and container version.