WebSocket: error — Ereignis · JavaScript-Referenz

Signatur

webSocket.addEventListener("error", handler)

Beschreibung

Das error-Ereignis eines WebSocket-Objekts signalisiert, dass die Verbindung durch einen Fehler beendet wurde, zum Beispiel wenn der Server nicht erreichbar ist, der Handshake scheitert oder Daten nicht übertragen werden konnten. Du registrierst es entweder mit addEventListener("error", handler) oder über die Eigenschaft onerror.

Das übergebene Objekt ist ein einfaches Event. Es enthält keine Fehlermeldung, keinen Statuscode und keinen Grund. Das ist Absicht: Browser verraten Skripten aus Sicherheitsgründen nicht, warum eine Verbindung fehlgeschlagen ist, damit sich damit keine Netzwerke ausspähen lassen. Genauere Informationen bekommst du erst im danach folgenden close-Ereignis über CloseEvent.code und CloseEvent.reason. Meistens ist das Code 1006 (unerwartet abgebrochene Verbindung).

Typische Einsatzfälle sind das Protokollieren von Fehlern, das Anzeigen eines Offline-Hinweises in der Oberfläche und das Vorbereiten einer automatischen Neuverbindung. Die eigentliche Logik zum Neuverbinden gehört jedoch besser in den close-Handler: close wird nach error immer ausgelöst, error aber nicht bei jedem Verbindungsende.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname, hier immer `"error"`.
$handler Pflicht	(event: Event) => void		Callback, der ein generisches `Event` erhält. `event.target` ist der betroffene `WebSocket`.
$options	boolean \| AddEventListenerOptions	false	Optionale Einstellungen wie `{ once: true }` oder `{ signal }` zum späteren Entfernen über einen `AbortController`.

Beispiele

Fehler mit addEventListener abfangen

const socket = new WebSocket("wss://example.invalid/chat");

socket.addEventListener("error", (event) => {
  // event enthält keine Fehlermeldung – nur Typ und Ziel
  console.error("WebSocket-Fehler:", event.type, event.target.url);
  console.log("readyState:", socket.readyState); // 3 = CLOSED
});

socket.addEventListener("close", (event) => {
  console.log(`Geschlossen – Code ${event.code}, sauber: ${event.wasClean}`);
});

WebSocket-Fehler: error wss://example.invalid/chat readyState: 3 Geschlossen – Code 1006, sauber: false

onerror-Eigenschaft und Status in der Oberfläche

const statusEl = document.querySelector("#status");
const socket = new WebSocket("wss://echo.websocket.org");

socket.onopen = () => {
  statusEl.textContent = "Verbunden";
};

socket.onerror = () => {
  statusEl.textContent = "Verbindungsfehler – bitte später erneut versuchen";
};

// Handler wieder entfernen
// socket.onerror = null;

Automatische Neuverbindung mit Backoff

const connect = (url, attempt = 0) => {
  const controller = new AbortController();
  const socket = new WebSocket(url);

  socket.addEventListener("open", () => {
    attempt = 0;
    console.log("Verbunden");
  }, { signal: controller.signal });

  socket.addEventListener("error", () => {
    console.warn("Fehler aufgetreten, warte auf close …");
  }, { signal: controller.signal });

  // Neuverbindung im close-Handler, da close immer nach error folgt
  socket.addEventListener("close", () => {
    controller.abort(); // alle Listener entfernen
    const delay = Math.min(30000, 1000 * 2 ** attempt);
    console.log(`Neuer Versuch in ${delay} ms`);
    setTimeout(() => connect(url, attempt + 1), delay);
  }, { signal: controller.signal });

  return socket;
};

connect("wss://example.com/live");

Fehler aufgetreten, warte auf close … Neuer Versuch in 1000 ms

// Wichtig · Fallstricke

Keine Fehlerdetails: Das Ereignis ist ein einfaches Event und kein ErrorEvent. Es gibt also kein message. Den Grund siehst du nur in den Entwicklerwerkzeugen des Browsers oder eingeschränkt über CloseEvent.code.
Reihenfolge: Nach error folgt immer close. Lege die Aufräum- und Neuverbindungslogik deshalb in den close-Handler, sonst läuft sie doppelt.
Keine Ausnahme: Wenn der Verbindungsaufbau scheitert, wirft der Konstruktor keine Ausnahme. Nur eine ungültige URL oder ein unzulässiges Protokoll löst sofort einen SyntaxError aus. Netzwerkfehler meldet der Browser ausschließlich über error und close.
send(): Ein Aufruf von send() auf eine geschlossene Verbindung löst kein error aus. Die Daten werden stillschweigend verworfen. Prüfe vorher readyState === WebSocket.OPEN.
Sicherheit: Verwende in Produktion wss://. Auf HTTPS-Seiten blockieren Browser ws:// als Mixed Content, und das äußert sich ebenfalls als error. WebSockets unterliegen nicht CORS. Der Server sollte deshalb den Origin-Header selbst prüfen.
Kompatibilität: Wird von allen modernen Browsern unterstützt, in Node.js ab Version 22 über das globale WebSocket.

Siehe auch

WebSocket WebSocket: close WebSocket: open WebSocket: message Worker: error