Memory exhaustion from orphaned session states in low-traffic environments

Session State Cleanup in Streamlit

Streamlit does not currently provide a native configuration parameter to define a strict server-side idle timeout for session cleanup. Session termination is primarily driven by the closure of the WebSocket connection or the failure of the browser-side heartbeat. Consequently, if a connection remains open but idle, or if the server fails to detect a socket closure promptly, the associated st.session_state remains allocated in RAM.

Likely Cause of Memory Growth

In low-traffic environments on minimal-tier hardware, memory exhaustion typically stems from one of two sources:

• Orphaned Sessions: WebSocket connections that haven't timed out on the server side, keeping session-specific objects alive.
• Global Cache Accumulation: While st.session_state is per-user, @st.cache_data is global. If the cached datasets are large and updated frequently, the global cache may be the primary driver of OOM errors rather than individual session states.

Mitigation Strategies

Since you cannot programmatically force the clearance of a session state without an active trigger from the client (as st.session_state.clear() requires the script to run), you must manage memory through infrastructure and cache constraints.

1. Limit Cache TTL: Prevent the global cache from growing indefinitely by implementing a ttl (time-to-live) on cached functions.

   @st.cache_data(ttl=3600) # Clear cache every hour

2. Externalize State: For high-memory objects, avoid storing them directly in st.session_state. Use a lightweight reference (like a UUID) and store the actual data in a database or a Redis instance with its own TTL.
3. Infrastructure Timeouts: If deploying behind a reverse proxy (e.g., Nginx), configure strict proxy_read_timeout and proxy_send_timeout settings to force the closure of idle TCP connections, which triggers Streamlit's session cleanup.

Verification

To determine if the leak is session-based or cache-based, run the following test:

• Open five separate browser tabs to trigger five distinct sessions.
• Monitor memory via htop or docker stats.
• Close the tabs and observe the memory drop. If memory remains high after several minutes, the issue is likely the global @st.cache_data rather than orphaned session states.

Missing Diagnostic: Are you storing large DataFrames or NumPy arrays directly inside st.session_state, or are those objects primarily handled by @st.cache_data?