Websocket message exceeding 32 MiB: server logs size error, then connection abort without close handshake

[emchristiansen]

Environment

• SpacetimeDB version: v2.2.0
• Image: docker.io/clockworklabs/spacetime:v2.2.0
• Image digest: sha256:bc85c24909f92983a7912c83e9e32d0dc3726f535886f76be87ce9222d698c3f
• Deployment: Kubernetes StatefulSet, single replica, --listen-addr=0.0.0.0:3000
• Client: Rust SDK (spacetimedb_sdk) connecting via websocket

Observed Behavior

A Rust SDK client sends a websocket message of 70,666,292 bytes (67.4 MiB) to a SpacetimeDB
v2.2.0 server. The server rejects the message due to a size limit and aborts the websocket
connection. The client receives a ResetWithoutClosingHandshake error.

Server Logs

Timestamps are UTC, captured via kubectl logs spacetimedb-0 -n ccc. One complete
connect/reject/abort cycle around the requested observation time of 17:02:30Z:

2026-05-06T17:02:29.914527Z DEBUG crates/client-api/src/routes/subscribe.rs:241:
  websocket: New client connected from unknown ip
  with Identity c2001aeb16590eed773b52c68da872638bfc661b5849a64394836e1d603c4a9c
  and ConnectionId 942b14ad35ed27d9b415c02d8ebdcd89

2026-05-06T17:02:29.914946Z DEBUG crates/client-api/src/routes/subscribe.rs:266:
  websocket: Database accepted connection [...]; spawning ws_client_actor and ClientConnection

2026-05-06T17:02:30.271716Z  WARN crates/client-api/src/routes/subscribe.rs:893:
  Websocket receive error: Space limit exceeded: Message too long: 70666292 > 33554432

2026-05-06T17:02:30.271851Z  INFO crates/client-api/src/routes/subscribe.rs:507:
  Client connection ended: ClientActorId(c2001aeb...@942b14ad.../106)

2026-05-06T17:02:30.272115Z  WARN crates/core/src/client/client_connection.rs:734:
  websocket connection aborted for client identity `c2001aeb...603c4a9c`
  and database identity `c2001f39...29cb7830`

The same cycle repeated 118 times within the observation window (first occurrence at
2026-05-06T17:00:13.619041Z, last at 2026-05-06T17:07:52.815523Z), with the same client
identity reconnecting after each abort. The message size was 70666292 and the limit was
33554432 in every occurrence.

Server-Side Limit

The 33,554,432-byte (32 MiB) limit is set at
crates/client-api/src/routes/subscribe.rs lines 218-221 (v2.2.0 tag):

let ws_config = WebSocketConfig::default()
    .max_message_size(Some(0x2000000))
    .max_frame_size(None)
    .accept_unmasked_frames(false);

The WebSocketOptions struct in the same file
(lines 357-392)
defines the fields exposed via config.toml: ping_interval, idle_timeout,
close_handshake_timeout, and incoming_queue_length. max_message_size and max_frame_size
are not fields of that struct.

v2.2.0 Websocket Transport Change

The v2.2.0 release notes
state:

We've introduced a new v3 WebSocket transport that batches multiple logical client messages
into a single frame, cutting per-message overhead while keeping the existing message model
intact (#4761).

[emchristiansen]

Correction / follow-up after digging into the code:

Not a v2.2.0 regression

The 32 MiB max_message_size limit (crates/client-api/src/routes/subscribe.rs:219) appears to predate v2.2.0 and was unchanged in the tags I checked. We hit it right after upgrading, but that timing was coincidental — our client→server payload had grown to exceed the existing limit independently.

That said, I initially suspected v2.2.0 because it introduced the v3 websocket transport with message batching (PR #4761). In v3, multiple logical ClientMessages are concatenated into a single websocket message (message_handlers_v3.rs deserializes v2 messages in a loop from one binary payload). The tungstenite max_message_size check applies to the entire reassembled websocket message before SpacetimeDB's handler sees it, so v3 batching could in principle push the aggregate websocket message past the 32 MiB limit even when individual logical messages wouldn't. That didn't apply in our case (the Rust SDK currently requests v2.bsatn.spacetimedb — see sdks/rust/src/websocket.rs:250 — and the payload was a single large message), but it may be worth considering for future v3 clients that batch aggressively.

Apologies for the misleading version attribution.

Connection close behavior on oversized messages

The current behavior is: tungstenite raises Error::Capacity(MessageTooLong { size, max_size }) during read_message, which SpacetimeDB's ws_recv_loop handles as WsError::Capacity(_) — it logs warn!("Websocket receive error: {e}") and breaks out of the receive loop (subscribe.rs:885-894). No close frame is sent back to the client. The client sees ResetWithoutClosingHandshake with no indication of the cause.

Contrast this with other server-initiated closes in the same codebase: when a client exceeds the incoming queue length, SpacetimeDB sends CloseFrame { code: CloseCode::Again, reason: "too many requests" } (subscribe.rs:921-924). And when handle_message returns an error, it sends CloseFrame { code: CloseCode::Error, reason: format!("{e:#}") } (subscribe.rs:794-797). The Capacity error path doesn't get this treatment because the error occurs during tungstenite's message reassembly, before SpacetimeDB's message handler is reached.

Would it be feasible to catch WsError::Capacity(_) specifically and send a close frame with close code 1009 / Message Too Big (RFC 6455 §7.4.1; tungstenite exposes this as CloseCode::Size) before breaking? That would let SDK clients surface a meaningful error message instead of a generic connection reset.

Client→server compression

Server→client messages are compressed (Brotli by default via SERVER_MSG_COMPRESSION_TAG_*), but client→server messages are raw BSATN with no compression layer. In our case the 67 MiB raw payload compresses to ~8 MiB with zstd — well under the limit. Client-side payload compression would avoid this class of failure for compressible messages. I realize it needs protocol support and decompressed-size accounting on the server side, but it would be a valuable addition.

Configurable inbound limit

The 32 MiB limit is reasonable as a default, but could it be exposed in config.toml (alongside the existing WebSocketOptions fields like incoming_queue_length and idle_timeout)? Deployments that knowingly send large messages could then raise it without patching.