docs/bugs/004_gradio_intermittent_loading.md

Bug Report: Intermittent Gradio UI Loading (Hydration/Timeout)

1. Symptoms

• Intermittent Loading: The UI sometimes fails to load, showing a blank screen or a "Connection Error" toast.
• Refresh Required: Users often have to hard refresh the page (Ctrl+Shift+R) multiple times to get the UI to appear.
• Mobile vs. Desktop: The issue appears to be more prevalent or noticeable on Desktop Web than on Mobile Web (possibly due to network conditions, caching, or layout differences).
• Environment: HuggingFace Spaces (Docker SDK).

2. Root Cause Analysis

Based on research into Gradio 5.x/6.x behavior on HuggingFace Spaces, this is likely due to a combination of:

A. SSR (Server-Side Rendering) Hydration Mismatch

Gradio 5+ introduced Server-Side Rendering (SSR) to improve initial load performance. However, on HuggingFace Spaces (which uses an iframe), there can be race conditions where the server-rendered HTML doesn't match what the client-side JavaScript expects, causing a "Hydration Error". When this happens, the React/Svelte frontend crashes silently or enters an inconsistent state, requiring a full refresh.

B. WebSocket Timeouts

HuggingFace Spaces enforces strict timeouts for WebSocket connections. If the app takes too long to initialize (e.g., loading heavy libraries or models), the initial handshake may fail.

• Mitigation: Our app is relatively lightweight on startup (lazy loading models), so this is secondary, but network latency can trigger it.

C. Browser Caching

Aggressive browser caching of the main bundle can sometimes cause version mismatches if the Space was recently rebuilt/redeployed.

3. Proposed Solution

Immediate Fix: Disable SSR

Forcing Client-Side Rendering (CSR) eliminates the hydration mismatch entirely. While this theoretically slightly slows down the "First Contentful Paint", it is much more robust for dynamic apps inside iframes.

Change in src/app.py:

demo.launch(
    # ... other args ...
    ssr_mode=False,  # Force Client-Side Rendering to fix hydration issues
)

Secondary Fixes (If needed)

• Increase Concurrency Limits: Ensure max_threads is sufficient if many users connect at once.
• Health Check: Add a simple lightweight endpoint to keep the Space "warm" if it sleeps aggressively.

4. Verification Plan

1. Apply ssr_mode=False to src/app.py.
2. Deploy to HuggingFace Spaces (fix/gradio-ui-final branch).
3. Test on Desktop (Chrome Incognito, Firefox) and Mobile.
4. Verify no "Connection Error" toasts appear on initial load.