Debugging Silent WebSocket Disconnects in Spring Boot (Tomcat 8KB Buffer Limit)

Large Payloads Challenge: The Hidden 8KB Limit

Real-time applications built on Spring Boot and WebSockets often work flawlessly—until they don’t. Small messages flow without issue, reconnects appear healthy, and everything looks stable in development.

Then a real-world payload arrives. A Base64-encoded audio chunk. A streamed AI response. A large STOMP message around 50–70 KB.

Suddenly, the WebSocket connection drops. The browser shows a reconnect. The server logs show nothing.

From the client’s perspective, the server simply vanished. From the server’s perspective, nothing happened at all. No exception. No stack trace. No warning.

At this point, most developers start debugging the wrong layers—STOMP configuration, message converters, broker settings, or even application logic— because there is no signal that the failure occurred below Spring Boot.

In the sections that follow, we’ll break down why this happens, how to confirm it using targeted logging, and the correct way to override Tomcat’s WebSocket limits in Spring Boot—without relying on brittle workarounds.

The Setup: “It Should Be Simple, Right?”

The architectural goal was straightforward: Capture real-time audio in the browser, encode it for transport, and stream it to a Spring Boot backend via a STOMP WebSocket. This is a standard pattern for modern multimodal AI applications where low-latency interaction is key.

The Client-Side: Browser to Socket

On the frontend, we use the MediaRecorder API to capture audio chunks. To send this over a text-based STOMP frame, we encode the binary blob into a Base64 string.

// app.js - Capturing and Publishing Audio
const reader = new FileReader();

reader.onload = () => {
  // Extract the Base64 string from the Data URL
  const base64Audio = reader.result.split(',')[1];
  
  const payload = {
    audioData: base64Audio,
    mimeType: recordedAudioBlob.type // e.g., 'audio/webm'
  };

  // For a typical 1-second audio clip, this payload is ~70KB
  console.log(`Publishing to /app/audio. Size: ${payload.audioData.length} bytes.`);
  
  stompClient.publish({
    destination: "/app/audio",
    body: JSON.stringify(payload)
  });
};

reader.readAsDataURL(recordedAudioBlob);

Server-side handler: Controller

@MessageMapping("/audio")
public void handleAudioMessage(AudioMessage audioMessage) {
    logger.info("Received audio message!");
    // ... process the audio
}

Investigation & Elimination

Checkpoint 1: Message Size Limits
First suspect — message size. Easy fix, right?

# application.properties
server.tomcat.websocket.max-text-message-buffer-size=10485760   # 10MB
spring.websocket.messaging.stomp.message-size-limit=10485760     # 10MB

@Override
public void configureWebSocketTransport(WebSocketTransportRegistration registration) {
    registration.setMessageSizeLimit(10 * 1024 * 1024);
    registration.setSendBufferSizeLimit(10 * 1024 * 1024);
}

Checkpoint 2: Spring Security Configuration
Secondary hypothesis involved Spring Security blocking the request. Disabling CSRF and CORS provided no resolution. Permitted all requests to /ws/** Disabled CSRF Even removed spring-boot-starter-security entirely Restarted the server, result ❌ Same silent disconnect.

The Breakthrough: Enabling Observability

When the framework is silent, you must force it to speak. Enabling DEBUG logging for the org.springframework.web.socket package revealed the underlying error code which was previously swallowed:

logging.level.org.springframework.web.socket=DEBUG
logging.level.org.springframework.messaging.simp=DEBUG
            

CloseStatus[code=1009, reason=The decoded text message was too big for the output buffer...]

The Workaround: Customizing the Container

The effective resolution required bypassing high-level Spring configuration and directly customizing the embedded Tomcat container. Specifically, the WsServerContainer needed explicit configuration to increase setMaxTextMessageBufferSize and setMaxBinaryMessageBufferSize beyond the default 8KB.

@Bean
public WebServerFactoryCustomizer tomcatCustomizer() {
   return factory -> factory.addContextCustomizers(context ->
       context.addServletContainerInitializer((sci, servletContext) -> {
           org.apache.tomcat.websocket.server.WsServerContainer container =
               (org.apache.tomcat.websocket.server.WsServerContainer)
                   servletContext.getAttribute("jakarta.websocket.server.ServerContainer");
           if (container != null) {
               // Customizing the container to increase the buffer size
               int bufferSize = 10 * 1024 * 1024;
               container.setMaxTextMessageBufferSize(bufferSize);
               container.setMaxBinaryMessageBufferSize(bufferSize);
           }
       }, null)
   );
}

Official Framework Recognition & Resolution

This behavior was confirmed after i opened an issue with the Spring Boot team and discussed it directly with a core maintainer, leading to documentation updates for improved clarity.

With GitHub issue 47944 the Spring team acknowledged the documentation gap and provided a resolution. Andy Wilkinson from the core team has since opened Spring Boot Issue #47951 to address the documentation gap and that issue has been closed with a resolution.

The Immediate Fix (via Servlet Context)

server.servlet.context-parameters.org.apache.tomcat.websocket.binaryBufferSize=512000
server.servlet.context-parameters.org.apache.tomcat.websocket.textBufferSize=512000
        

The Long-term/future Fix (via Custom Configuration)

server.tomcat.websocket.max-binary-message-buffer-size=512KB
server.tomcat.websocket.max-text-message-buffer-size=512KB
        

How to Reproduce Silent WebSocket Disconnects Locally

To validate that the silent WebSocket disconnect is caused by Tomcat’s default 8KB buffer limit—and not application logic—I created a minimal, reproducible Spring Boot project.
The repository demonstrates:

• A failing scenario using Tomcat’s default WebSocket buffer configuration
• A toggleable workaround that prevents the disconnect by adjusting the buffer size

• Steps:
  • Clone the repo and navigate to the project directory.
  • Set server.tomcat.max-websocket-message-size.override=false in application.properties.
  • Run the app and connect via http://localhost:8080.
  • Send a 5-10 second audio recording.
  • Observe the CloseStatus[code=1009] in the server logs.

Conclusion

Modern frameworks like Spring Boot provide excellent abstractions, but they sit atop deep technology stacks (like Tomcat). When high-level configurations strictly fail to resolve resource limit issues, it is often necessary to inspect and configure the underlying container's defaults.