CloseEvent.reason — Eigenschaft · JavaScript-Referenz

Signatur

CloseEvent.reason

Beschreibung

Die schreibgeschützte Eigenschaft reason eines CloseEvent enthält eine kurze Erklärung in Textform, warum eine WebSocket-Verbindung geschlossen wurde. Der Text stammt aus dem Close-Frame, den die Gegenseite (meist der Server) gesendet hat. Er passt zum numerischen Statuscode in CloseEvent.code.

Sinnvoll ist reason vor allem für Logging, Fehlersuche und Hinweise an Nutzer, zum Beispiel „Sitzung abgelaufen“ oder „Server wird neu gestartet“. Für Programmentscheidungen wie einen erneuten Verbindungsaufbau sollte man sich dagegen auf code und wasClean stützen, denn der Text ist frei wählbar und nicht standardisiert.

Hat die Gegenseite keinen Grund angegeben oder wurde die Verbindung unsauber getrennt (z. B. Netzwerkabbruch, Code 1006), ist reason ein leerer String. Der Client kann selbst einen Grund mitschicken, indem er WebSocket.close(code, reason) aufruft. Diesen Text sieht dann der Server.

Rückgabewert

Typ

string

Beschreibung

Der UTF-8-dekodierte Grund aus dem Close-Frame. Ist kein Grund vorhanden, wird ein leerer String "" zurückgegeben.

Beispiele

Grund beim Schließen protokollieren

const ws = new WebSocket('wss://echo.example.com/socket');

ws.addEventListener('close', (event) => {
  const grund = event.reason || '(kein Grund angegeben)';
  console.log(`Verbindung geschlossen – Code ${event.code}: ${grund}`);
});

Verbindung geschlossen – Code 1001: Server wird neu gestartet

Nutzerhinweis und Wiederverbindung abhängig von code/reason

const connect = (url, versuch = 0) => {
  const ws = new WebSocket(url);

  ws.onclose = ({ code, reason, wasClean }) => {
    if (code === 4001) {
      // Anwendungsspezifischer Code: Anmeldung abgelaufen
      alert(`Bitte neu anmelden: ${reason}`);
      return;
    }
    if (!wasClean && versuch < 5) {
      const delay = 1000 * 2 ** versuch;
      console.warn(`Unerwartet getrennt (${code}) ${reason}. Neuer Versuch in ${delay} ms`);
      setTimeout(() => connect(url, versuch + 1), delay);
    }
  };
  return ws;
};

connect('wss://chat.example.com/live');

Unerwartet getrennt (1006) . Neuer Versuch in 1000 ms

Eigenen Grund senden und CloseEvent synthetisch erzeugen

// Client schließt selbst mit Grund (max. 123 Byte UTF-8)
const ws = new WebSocket('wss://example.com/socket');
ws.onopen = () => ws.close(1000, 'Tab geschlossen');

// CloseEvent zum Testen manuell erzeugen
const ev = new CloseEvent('close', { code: 4000, reason: 'Test-Abbruch', wasClean: true });
console.log(ev.reason);

Test-Abbruch

// Wichtig · Fallstricke

Längenlimit: Laut Protokoll darf der Grund höchstens 123 Byte (UTF-8) lang sein. Ruft man WebSocket.close() mit einem längeren Text auf, wirft der Browser einen SyntaxError. Bei Umlauten und Emojis zählen die Bytes, nicht die Zeichen.
Oft leer: Bei Netzwerkabbrüchen (Code 1006) oder wenn der Server keinen Grund schickt, ist reason ein leerer String. Deshalb immer einen Ersatztext vorsehen.
Nicht zur Steuerung verwenden: Programmlogik sollte sich auf code stützen (eigene Codes im Bereich 4000–4999), nicht auf Textvergleiche mit reason.
Sicherheit: Der Text kommt von der Gegenseite. Vor der Anzeige im DOM also textContent verwenden, nicht innerHTML, sonst droht XSS.
Die Eigenschaft ist schreibgeschützt. Eigene Werte lassen sich nur über den Konstruktor new CloseEvent(type, { reason }) setzen.
Wird in allen modernen Browsern und in Node.js ab Version 22 (globaler WebSocket) unterstützt.

Siehe auch

CloseEvent CloseEvent.code CloseEvent.wasClean WebSocket.close() WebSocket ElementInternals.ariaSort