API Gateway WebSocket - Invalid Frame Header

Question

Hello, I was having an intermittent issue when using API Gateway WebSocket where my client would disconnect with Invalid Frame Header showing in the network tab.

For my specific issue, our server (Lambda) requests data and then splits it into 12 frames. I then call postToConnection (12 times in parallel) and there are 12 success responses (`{}`). When looking at the client, I see a few of the messages coming through and then I get the Invalid Frame Header causing the client to disconnect from the socket.

I've inspected the network traffic using Wireshark and I can see that the Invalid Frame Header occurs because two frames are being combined into one resulting in the client error. I've switched to serializing the requests which has addressed the issue however there's still a possibility that two lambdas will try to call postToConnection at the same time to the same connection (although unlikely).

My question is whether this is a bug with API Gateway or if consumers are responsible for ensuring that only a single postToConnection is called at a time per connection?

Giovanni Lauria · Answer

According to the AWS documentation, API Gateway WebSocket APIs use a single TCP connection for each WebSocket connection. This means that if multiple concurrent requests are made to the same WebSocket connection, there is a potential for data race conditions and interleaving of frames, which can cause the client to receive corrupted or invalid frames.

While API Gateway aims to maintain the correct order of messages sent to a WebSocket connection, it cannot guarantee that frames from concurrent requests won't be interleaved, especially if the responses are sent back in a different order than the requests were received.

To address this issue, the recommended approach is to ensure that only one request is processed at a time for a given WebSocket connection. This can be achieved by implementing a synchronization mechanism in your application logic, such as using a lock or a queue.

API Gateway WebSocket - Invalid Frame Header

Relevant content