Websocket message size limits with large st.dataframe payloads

The Serialization Bottleneck

p>In Streamlit, st.dataframe and st.data_editor utilize client-side virtualization, which means only the visible rows are rendered in the DOM. However, the **entire dataset** must be serialized (typically into Apache Arrow or JSON) and sent over the WebSocket before this virtualization can take place.

When dealing with large payloads, the failure is usually not a hard 'limit' within Streamlit itself, but rather one of three factors:

• Proxy Limits: Tools like Nginx or HAProxy often have a client_max_body_size or timeout settings that drop large WebSocket frames.
• Browser Memory Exhaustion: The browser may crash while attempting to parse a massive serialized string into memory.
• Heartbeat Timeouts: If serialization takes too long, the server may fail to send a heartbeat, causing a 'Connection is lost' error.

Resolution Strategies

To handle datasets that exceed practical payload sizes, move away from client-side virtualization toward server-side control:

1. Manual Pagination (Server-Side)

Instead of passing the full DataFrame to st.dataframe, use st.session_state to track the current page and slice the data on the server.

import streamlit as st
import pandas as pd

if 'page' not in st.session_state:
    st.session_state.page = 0
page_size = 100

# Load data once cached
df = st.cache_data(load_large_data)

# Slice data before sending to client
start = st.session_state.page * page_size
end = start + page_size
st.dataframe(df.iloc[start:end])

col1, col2 = st.columns(2)
with col1:
    if st.button("Previous") and st.session_state.page > 0:
        st.session_state.page -= 1
        st.rerun()
with col2:
    if st.button("Next") and end < len(df):
        st.session_state.page += 1
        st.rerun()

2. Query Bounding

If the user needs to see specific subsets, implement filters (date ranges, category selectors) that filter the DataFrame before it reaches the rendering component. This ensures the WebSocket payload remains small regardless of total dataset size.

Assumptions and Uncertainties

The optimal threshold for switching to manual paging is hardware-dependent; generally, datasets exceeding 50,000–100,000 rows (depending on column count) will cause noticeable lag in standard Streamlit components. Regarding consistency with st.data_editor: if you modify a paginated view, you must manually map those changes back to the master cached DataFrame in st.session_state, as the component only knows about the current slice.

To provide a more specific recommendation, are you experiencing specific connection-drop errors, or is the browser UI simply freezing?