Serializer.decode() crashes when Realtime server sends non-array WebSocket message

[whaaaley]

Describe the bug

Serializer.decode() crashes when the Realtime server sends a JSON object over the WebSocket instead of the expected array format. This crashes the entire process with an unhandled TypeError.

Library affected

supabase-js

Reproduction

No response

Steps to reproduce

1. Subscribe to postgres_changes on a table
2. Trigger an INSERT via a cron job or external process
3. The Realtime server occasionally sends a non-array JSON message
4. Process crashes with the stack trace below

System Info

- @supabase/supabase-js: ^2.56.0
- @supabase/realtime-js: 2.93.3
- Runtime: Deno 2.6.3
- Local Supabase via supabase start

Used Package Manager

npm

Logs

error: Uncaught TypeError: jsonPayload is not iterable
            const [join_ref, ref, topic, event, payload] = jsonPayload;
                                                           ^
    at Serializer.decode (realtime-js/dist/main/lib/serializer.js:104:60)
    at RealtimeClient._onConnMessage (realtime-js/dist/main/RealtimeClient.js:455:14)
    at WebSocket.conn.onmessage (realtime-js/dist/main/RealtimeClient.js:519:47)

Validations

• Follow our Code of Conduct
• Read the Contributing Guidelines.
• Read the docs.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
• Make sure this is a Supabase JS Library issue and not an issue with the Supabase platform. If it's a Supabase platform related bug, it should likely be reported to supabase/supabase instead.
• Check that this is a concrete bug. For Q&A open a GitHub Discussion or join our Discord Chat Server.
• The provided reproduction is a minimal reproducible example of the bug.

[7ttp]

hi @whaaaley 💚🙌
thanks for reporting! Unfortunately,
I wasn't able to reproduce this on my end.
might be an edge case

@mandarini should I add a defensive check here anyway? 😅

[mandarini]

@7ttp sure please do! Thank you!

[mandarini]

Thanks for reporting this @whaaaley! Before we proceed with a fix, we need to understand the root cause better. According to the Phoenix Socket protocol spec, the Realtime server always sends messages as 5-element JSON arrays in this format:

[join_ref, ref, topic, event, payload]

This is enforced throughout the Realtime server codebase.

To better understand what's happening, could you provide:

1. The actual malformed message content - Can you add logging to capture what the raw WebSocket message looks like when this crash occurs?

   // Temporary debug logging
   if (typeof rawPayload === 'string') {
     const parsed = JSON.parse(rawPayload)
     if (!Array.isArray(parsed) || parsed.length < 5) {
       console.error('Malformed Realtime message:', parsed)
     }
   }

2. Your infrastructure setup - Are you using:

   • Any proxies, load balancers, or CDNs (Cloudflare, nginx, etc.)?
   • Any WebSocket middleware?
   • Self-hosted Realtime or Supabase hosted?

3. Minimal reproduction repository - Is there a specific sequence of operations that triggers this?

If the server is genuinely sending non-array messages, that would be a critical bug in @supabase/realtime that we need to address server-side. However, it could also be:

• A network middleware issue (proxy/load balancer modifying messages)
• Connection errors being misinterpreted as protocol messages
• Edge case in your specific setup

Let's get to the bottom of this!

[yukimotochern]

I created a draft pr for handling edge cases. #2130.