new WebTransportError() — Methode · JavaScript-Referenz

Signatur

new WebTransportError(message, options)

Beschreibung

Der Konstruktor WebTransportError() erzeugt eine Instanz von WebTransportError. Diese Klasse erbt von DOMException (Name immer "WebTransportError") und hat zwei zusätzliche Eigenschaften: source gibt an, ob der Fehler vom Stream ("stream") oder von der ganzen Sitzung ("session") stammt. streamErrorCode enthält einen anwendungsspezifischen Fehlercode oder null.

Meist erzeugt der Browser solche Objekte selbst, zum Beispiel wenn eine Verbindung abbricht, transport.ready bzw. transport.closed abgelehnt wird oder die Gegenseite einen Stream zurücksetzt. Selbst aufrufen lohnt sich vor allem in zwei Fällen: wenn du einen Stream mit WritableStream.abort(), ReadableStream.cancel() oder controller.error() gezielt mit einem Fehlercode beenden willst, den der Server auswerten kann, oder wenn du in Tests und Mocks realistische Fehler nachbilden möchtest.

Der Fehlercode, den du über streamErrorCode an abort() oder cancel() übergibst, wird als Anwendungsfehlercode an die Gegenseite gesendet (RESET_STREAM oder STOP_SENDING in HTTP/3). So kann der Server zwischen verschiedenen Abbruchgründen unterscheiden.

Parameter

Name	Typ	Default	Beschreibung
$message	string	""	Lesbare Fehlerbeschreibung. Landet in der geerbten Eigenschaft `message`.
$options	Object	{}	Optionales Objekt mit weiteren Angaben zum Fehler (siehe unten).
$options.source	"stream" \| "session"	"stream"	Quelle des Fehlers: `"stream"` für einen einzelnen Stream, `"session"` für die gesamte WebTransport-Sitzung.
$options.streamErrorCode	number \| null	null	Anwendungsspezifischer Fehlercode als vorzeichenlose 32-Bit-Ganzzahl. Werte außerhalb des Bereichs werden begrenzt (Clamp), nicht abgeschnitten.

Rückgabewert

Typ

WebTransportError

Beschreibung

Ein neues WebTransportError-Objekt (Unterklasse von DOMException) mit den Eigenschaften name, message, source und streamErrorCode.

Beispiele

Fehlerobjekt erzeugen und auswerten

const err = new WebTransportError('Upload abgebrochen', {
  source: 'stream',
  streamErrorCode: 42,
});

console.log(err.name);
console.log(err.message);
console.log(err.source, err.streamErrorCode);
console.log(err instanceof DOMException);

WebTransportError Upload abgebrochen stream 42 true

Unidirektionalen Stream mit Fehlercode abbrechen

const transport = new WebTransport('https://example.com:4433/upload');
await transport.ready;

const stream = await transport.createUnidirectionalStream();
const writer = stream.getWriter();

try {
  await writer.write(new TextEncoder().encode('Teil 1'));
  // Nutzer bricht ab -> Server erhält Code 7 (z. B. "vom Nutzer abgebrochen")
  await writer.abort(new WebTransportError('Vom Nutzer abgebrochen', {
    streamErrorCode: 7,
  }));
  console.log('Stream zurückgesetzt');
} catch (e) {
  console.error('Fehler beim Schreiben:', e);
}

Stream zurückgesetzt

Browser-Fehler einer Sitzung unterscheiden

const transport = new WebTransport('https://example.com:4433/chat');

transport.closed
  .then(({ closeCode, reason }) => {
    console.log(`Sauber geschlossen: ${closeCode} ${reason}`);
  })
  .catch((err) => {
    if (err instanceof WebTransportError) {
      console.warn(`Fehler (${err.source}):`, err.message, err.streamErrorCode);
    } else {
      console.error('Unerwarteter Fehler:', err);
    }
  });

Fehler (session): … null

Fehler in Tests nachbilden

// Mock für einen Reader, der mit einem Server-Reset abbricht
const mockStream = new ReadableStream({
  start(controller) {
    controller.enqueue(new Uint8Array([1, 2, 3]));
    controller.error(new WebTransportError('Reset durch Server', {
      streamErrorCode: 500,
    }));
  },
});

const reader = mockStream.getReader();
await reader.read();
try {
  await reader.read();
} catch (err) {
  console.log(err.name, err.streamErrorCode);
}

WebTransportError 500

// Wichtig · Fallstricke

Kompatibilität: WebTransport und damit WebTransportError gibt es in Chromium-Browsern ab Version 97 und in Firefox ab 114. Safari unterstützt es noch nicht oder nur teilweise. Prüfe die Unterstützung vorher mit 'WebTransportError' in globalThis.
Nur in sicheren Kontexten (HTTPS) verfügbar. Der Server muss HTTP/3 mit WebTransport sprechen.
streamErrorCode wird bei Werten außerhalb von 0 bis 2³²−1 begrenzt. Ein negativer Wert wird zu 0. Nicht-ganzzahlige Werte werden gerundet.
Nicht jeder Fehlercode kommt beim Server an. Übertragen wird er nur, wenn du das Objekt an abort() oder cancel() übergibst. Andere Fehlertypen führen dazu, dass der Code 0 gesendet wird.
source und streamErrorCode sind nur lesbar. Setzen kannst du sie ausschließlich über den Konstruktor.
Fehler, die der Browser selbst erzeugt, haben bei Sitzungsfehlern meist source: \"session\" und streamErrorCode: null. Prüfe beide Werte, bevor du sie weiterverarbeitest.

Siehe auch

WebTransportError WebTransport DOMException WebTransport.closed WritableStream.prototype.abort() ReadableStream.prototype.cancel() new CSSTransformValue()