Showing a “session timed out” message after Streamlit WebSocket disconnect

Using Streamlit
,
1

Hi Streamlit community,

I’m trying to determine whether it’s possible to show a custom message (e.g., “This page has timed out. Please refresh to continue.”) after a Streamlit session expires and the WebSocket connection is closed.

Our app sits behind a load balancer, and I initially suspected the issue was related to the load balancer’s idle timeout. I experimented with adjusting that timeout, but the app’s behavior didn’t change in a way that would allow us to detect the disconnect or render a message, which suggests the WebSocket lifecycle is still fully managed by Streamlit.

From what I understand, once the WebSocket disconnects, the app can no longer execute code or update the UI, making it difficult (or impossible) to display anything after the fact.

My questions:

  1. Is there a supported way to detect an impending session timeout and display a message before the connection closes?

  2. Is it possible to render custom UI after the WebSocket has disconnected?

  3. If not, is this simply outside Streamlit’s design constraints?

I want to confirm I’m not missing a recommended pattern or best practice before treating this as a framework limitation.

Thanks for any guidance

2

Welcome to the Streamlit community and thanks for your thoughtful question! You’re absolutely right in your understanding: once the WebSocket connection between the client and server is closed (due to a load balancer timeout, network issue, or Streamlit’s own session management), the Streamlit app cannot execute any Python code or update the UI. There is currently no supported way to render a custom message after the WebSocket disconnects, nor is there a built-in mechanism to detect an impending session timeout and proactively display a warning before the connection is lost. The session state and UI are only accessible while the connection is active, and Streamlit does not provide hooks for handling disconnect events or customizing the default error dialogs shown to users after a disconnect occurs.

This is a known limitation and is by design—Streamlit’s architecture relies on a persistent WebSocket for real-time updates, and once that’s gone, the frontend cannot communicate with the backend to trigger UI changes. Some users have tried workarounds (like using JavaScript injected via components to listen for unload events), but these are not officially supported and can be unreliable. If you need to warn users about impending timeouts, you’d need to implement a client-side timer using a custom component or JavaScript, but this would be outside the standard Streamlit API and not robust against all disconnect scenarios. For now, customizing the post-disconnect UI is not possible within Streamlit’s supported patterns. See the discussion and confirmation of these limitations in the Streamlit forums and official docs.

Sources: