Dart WebSocketStatus

last modified October 18, 2026

The WebSocketStatus class in Dart defines the standard close codes for WebSocket connections, such as normal closure or protocol error. Connection states are exposed separately as constants on the WebSocket class.

WebSocketStatus contains static integer close codes defined by the WebSocket protocol. They are reported in WebSocket.closeCode or passed to WebSocket.close.

Basic Definition

WebSocketStatus is a class containing static close-code constants for WebSocket connections. It's part of Dart's dart:io library.

Key close codes include normalClosure, goingAway, protocolError, abnormalClosure, and messageTooBig. The ready-state values connecting, open, closing, and closed are constants on WebSocket.

Checking Connection Status

This example shows how to check basic WebSocket connection status.

import 'dart:io';

void main() async {
  var socket = await WebSocket.connect('ws://echo.websocket.org');
  
  if (socket.readyState == WebSocket.open) {
    print('Connection is open');
  } else if (socket.readyState == WebSocket.connecting) {
    print('Still connecting');
  }
  
  await socket.close();
}

We connect to a WebSocket server and check its readyState against WebSocket constants. The open state indicates a successful connection.

$ dart main.dart
Connection is open

Handling Connection Errors

This example demonstrates handling transport and WebSocket handshake failures.

import 'dart:io';

void main() async {
  try {
    await WebSocket.connect('ws://localhost:8080');
  } on WebSocketException catch (e) {
    print('WebSocket error: ${e.message}');
    print('HTTP status code: ${e.httpStatusCode}');
  } on SocketException {
    print('Connection failed: could not reach server');
  }
}

We attempt to connect to a server that is not running. A failed handshake is reported as a WebSocketException, which exposes the message and optional httpStatusCode fields. A transport failure is reported as a SocketException.

$ dart main.dart
Connection failed: could not reach server

Monitoring State Changes

This example shows tracking WebSocket state transitions.

import 'dart:io';

void main() async {
  var socket = await WebSocket.connect('ws://echo.websocket.org');
  print('Initial state: ${socket.readyState}');
  
  socket.listen(
    (_) {},
    onDone: () {
      print('Final state: ${socket.readyState}');
      if (socket.readyState == WebSocket.closed) {
        print('Connection closed normally');
      }
    }
  );
  
  await socket.close();
}

We monitor the WebSocket's state changes from open to closed. The onDone callback checks the final state after connection closure.

$ dart main.dart
Initial state: 1
Final state: 3
Connection closed normally

Protocol Error Handling

This example demonstrates interpreting a close code reported by a peer.

import 'dart:io';

void describeCloseCode(int? code) {
  switch (code) {
    case WebSocketStatus.normalClosure:
      print('Normal closure');
      break;
    case WebSocketStatus.protocolError:
      print('Protocol error');
      break;
    case WebSocketStatus.abnormalClosure:
      print('Abnormal closure');
      break;
    default:
      print('Other close code: $code');
  }
}

void main() {
  describeCloseCode(WebSocketStatus.protocolError);
}

WebSocketStatus constants are close codes, not ready-state values. We map the protocolError code to a message. After a connection closes, the code sent by the peer is available through WebSocket.closeCode.

$ dart main.dart
Protocol error

Connection Lifecycle Tracking

This example shows tracking all possible WebSocket states.

import 'dart:async';
import 'dart:io';

void printState(int state) {
  switch (state) {
    case WebSocket.connecting:
      print('Connecting');
      break;
    case WebSocket.open:
      print('Open');
      break;
    case WebSocket.closing:
      print('Closing');
      break;
    case WebSocket.closed:
      print('Closed');
      break;
    default:
      print('Unknown state');
  }
}

void main() async {
  var socket = await WebSocket.connect('ws://echo.websocket.org');
  printState(socket.readyState);

  var done = Completer<void>();
  socket.listen((_) {}, onDone: done.complete);

  socket.add('Hello');
  await socket.close();
  await done.future;
  printState(socket.readyState);
}

We create a helper function to translate status codes to human-readable strings. This shows the complete connection lifecycle from connecting to closed.

$ dart main.dart
Open
Closed

Best Practices

• State checks: Always verify connection state before sending data
• Error handling: Handle all possible error states gracefully
• Cleanup: Properly close connections when done
• Monitoring: Track state changes for debugging

Source

Dart WebSocketStatus Documentation

This tutorial covered Dart's WebSocketStatus close codes and the WebSocket ready-state constants, with practical examples showing connection monitoring, error handling, and state management for WebSockets.

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.

List all Dart tutorials.