Flutter socket_io_client fails: Connection was not upgraded to websocket
WebSocketException: Connection to '...' was not upgraded to websocketShort 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.
Fix it fast
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"2Match what you see, then jump to its fix
- 1
The first request goes out as polling, or the Dart VM client never connectsThe client is not forced to the websocket transportFix - 2
The handshake fails with Unsupported protocol version, or connects and drops at onceClient and server major versions do not matchFix - 3
Works on the server's own port, fails behind nginx, with TRANSPORT_MISMATCH on the serverA reverse proxy drops the Upgrade headersFix - 4
The client reaches the host but never the Socket.IO endpointThe Socket.IO path differs between client and serverFix
- 1
What does the error look like?
WebSocketException: Connection to '...' was not upgraded to websocketUnsupported 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 runConfirmed by pub.dev
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.io2Fix
Move the client or the server to a matching pair.
flutter pub add socket_io_client
# or on the server
npm install socket.io@latest3Verify
Repeat the curl handshake test, then run the app.
curl "https://example.com/socket.io/?EIO=4&transport=polling"Confirmed by socket.io
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 nginxConfirmed by nginx.org
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 options3Verify
Reconnect; the server's connection event fires.
flutter runConfirmed by socket.io
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- SessionBirdAn omnichannel engagement suite in Flutter: campaigns, chatbot, tickets, analytics and live calling.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
Related fixes
Back end
Socket.IO answers 404 on the polling request
Cannot GET /socket.io/
A 404 on /socket.io/?EIO=4&transport=polling means the request is not reaching a Socket.IO server.
3 causes, each with a fixServers
WebSockets behind nginx drop when the connection is idle
transport close
nginx closes a proxied connection when the backend sends no data for 60 seconds, and a quiet WebSocket looks exactly like that.
3 causes, each with a fixMobile 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 fixMobile apps
Gradle cannot find com.google.firebase:firebase-analytics-ktx
Required by: project :app
Firebase moved the Kotlin extensions into the main modules and stopped releasing the -ktx modules in July 2025.
2 causes, each with a fixMobile apps
Gradle cannot create LibraryVariantBuilderImpl in a Flutter Android build
Could not create an instance of type com.android.build.api.variant.impl.LibraryVariantBuilderImpl
This error appears when the Android Gradle plugin (AGP) cannot run in the Gradle or IDE you use.
3 causes, each with a fixMobile apps
Flutter release build cannot open the keystore: HmacPBESHA256 not available
Algorithm HmacPBESHA256 not available
The keystore is a PKCS12 file protected by a newer algorithm than the Java that is reading it understands.
3 causes, each with a fix