Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

Flutter socket_io_client fails: Connection was not upgraded to websocket

ErrorWebSocketException: Connection to '...' was not upgraded to websocket

Short answer

The Dart client speaks WebSocket only, so the server or the proxy in front of it must complete a WebSocket upgrade. Set the websocket transport on the client, match the client and server major versions, forward Upgrade headers in the proxy, and use the same Socket.IO path on both sides.

  • Applies to Flutter 3.35, socket_io_client 3.x, Socket.IO 4.8, nginx 1.26
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check from a terminal that the server answers a Socket.IO handshake at all. A healthy v3 or v4 server replies with a body that starts with 0 and a sid.

    curl "https://example.com/socket.io/?EIO=4&transport=polling"
  2. 2Match what you see, then jump to its fix

    1. 1The first request goes out as polling, or the Dart VM client never connectsThe client is not forced to the websocket transportFix
    2. 2The handshake fails with Unsupported protocol version, or connects and drops at onceClient and server major versions do not matchFix
    3. 3Works on the server's own port, fails behind nginx, with TRANSPORT_MISMATCH on the serverA reverse proxy drops the Upgrade headersFix
    4. 4The client reaches the host but never the Socket.IO endpointThe Socket.IO path differs between client and serverFix

What does the error look like?

  • WebSocketException: Connection to '...' was not upgraded to websocket
  • Unsupported protocol version

Cause 1 of 4

The client is not forced to the websocket transport

1Check

In Flutter and the Dart VM the client works with dart:io websockets, so the transport list must say websocket.

grep -n "io(\|IO.io\|setTransports" -r lib/

2Fix

Build the options with setTransports(['websocket']) and connect.

import 'package:socket_io_client/socket_io_client.dart' as IO;

final socket = IO.io(
  'https://example.com',
  IO.OptionBuilder().setTransports(['websocket']).build(),
);
socket.onConnect((_) => print('connected'));

3Verify

The onConnect callback prints and the server logs a new connection.

flutter run

Confirmed by pub.dev

Did this fix it?

Cause 2 of 4

Client and server major versions do not match

1Check

socket_io_client 0.9 to 1.x talks to Socket.IO 2.x servers, 2.x to servers 3.x to 4.6, and 3.x to servers 4.7 and later.

flutter pub deps | grep socket_io_client
npm ls socket.io

2Fix

Move the client or the server to a matching pair.

flutter pub add socket_io_client
# or on the server
npm install socket.io@latest

3Verify

Repeat the curl handshake test, then run the app.

curl "https://example.com/socket.io/?EIO=4&transport=polling"

Confirmed by socket.io

Did this fix it?

Cause 3 of 4

A reverse proxy drops the Upgrade headers

1Check

Upgrade and Connection are hop-by-hop headers, so nginx does not pass them on unless you set them.

sudo nginx -T | grep -n "Upgrade\|proxy_http_version"

2Fix

Set both headers on the Socket.IO location, and a longer read timeout so idle connections survive.

location /socket.io/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 1h;
}

3Verify

Test the config, reload nginx and reconnect the app.

sudo nginx -t && sudo systemctl reload nginx

Confirmed by nginx.org

Did this fix it?

Cause 4 of 4

The Socket.IO path differs between client and server

1Check

The default path is /socket.io/. A namespace in the URL does not change it; a custom path must be set on both sides.

grep -rn "path:" server/ lib/

2Fix

Use the same path value on the server and in the client options, or leave both at the default.

// server
const io = new Server(httpServer, { path: "/my-custom-path/" });
// client: pass the same path in its options

3Verify

Reconnect; the server's connection event fires.

flutter run

Confirmed by socket.io

Did this fix it?

How do I stop it coming back?

  • Pin the server and client major versions together in the same ticket.
  • Run the curl handshake check in your deploy checklist.
  • Keep one nginx location block for /socket.io/ with the upgrade headers in it.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Mobile apps

Google Play says the app does not support 16 KB memory pages

check_elf_alignment.sh reports UNALIGNED for a library under lib/arm64-v8a

Google Play requires apps that target Android 15 or higher and ship native .so libraries to run on devices with 16 KB memory pages; from 1 February 2027 it will block updates that do not.

5 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.