new URIError() — Methode · JavaScript-Referenz

Signatur

new URIError(message, options)

Beschreibung

Mit dem Konstruktor URIError() erzeugt man ein Fehlerobjekt für Probleme beim Kodieren oder Dekodieren von URIs. Von selbst werfen JavaScript-Engines einen URIError, wenn z. B. decodeURIComponent() auf eine ungültige Prozent-Kodierung wie '%E0%A4%A' trifft oder encodeURIComponent() ein einzelnes Surrogat ('\uD800') bekommt.

Man kann den Konstruktor mit new oder ohne new aufrufen, beide Varianten liefern eine neue Instanz. URIError erbt von Error. Deshalb stehen message, name (Wert "URIError"), stack (nicht standardisiert, aber in allen Engines vorhanden) und seit ES2022 auch cause zur Verfügung.

Selbst geworfen wird ein URIError vor allem in eigenen Hilfsfunktionen zum Parsen oder Validieren von URLs. Aufrufer können den Fehler dann gezielt mit instanceof URIError von anderen Fehlerarten trennen. Über options.cause lässt sich der ursprüngliche Fehler anhängen, sodass die Fehlerkette erhalten bleibt.

Parameter

Name	Typ	Default	Beschreibung
$message	string	""	Optionale, für Menschen lesbare Fehlerbeschreibung. Werte, die kein String sind, werden in einen String umgewandelt. Fehlt der Wert, erbt die Instanz `message` als leeren String vom Prototyp.
$options	object		Optionales Objekt. Unterstützt wird die Eigenschaft `cause` (ES2022): Sie gibt die eigentliche Fehlerursache an und wird als eigene Eigenschaft `cause` an der Instanz gespeichert.

Rückgabewert

Typ

URIError

Beschreibung

Eine neue URIError-Instanz mit name === "URIError" und der übergebenen message.

Beispiele

URIError erzeugen und Eigenschaften prüfen

const err = new URIError('Ungültige Prozent-Kodierung');

console.log(err instanceof URIError); // true
console.log(err instanceof Error);    // true
console.log(err.name);                // URIError
console.log(err.message);

// Aufruf ohne new funktioniert ebenfalls
const err2 = URIError('Auch ohne new');
console.log(err2 instanceof URIError);

true true URIError Ungültige Prozent-Kodierung true

Automatisch geworfenen URIError abfangen

const safeDecode = (value) => {
  try {
    return decodeURIComponent(value);
  } catch (e) {
    if (e instanceof URIError) {
      console.warn(`Kann nicht dekodieren: ${value}`);
      return value; // Rohwert als Fallback
    }
    throw e;
  }
};

console.log(safeDecode('Stra%C3%9Fe'));
console.log(safeDecode('%E0%A4%A'));

Straße Kann nicht dekodieren: %E0%A4%A %E0%A4%A

Eigenen URIError mit cause werfen

const parseQueryParam = (query, key) => {
  const raw = new URLSearchParams(query.replace(/\+/g, '%2B')).get(key);
  try {
    return decodeURIComponent(raw ?? '');
  } catch (cause) {
    throw new URIError(`Parameter "${key}" ist fehlerhaft kodiert`, { cause });
  }
};

try {
  parseQueryParam('q=%25E0%25A4%25A', 'q');
} catch (e) {
  console.log(e.name, '-', e.message);
  console.log('Ursache:', e.cause.name);
}

URIError - Parameter "q" ist fehlerhaft kodiert Ursache: URIError

// Wichtig · Fallstricke

Automatische Auslöser: Von selbst werfen nur encodeURI(), encodeURIComponent(), decodeURI() und decodeURIComponent() einen URIError. Der Konstruktor new URL() wirft bei einer ungültigen URL dagegen einen TypeError, keinen URIError.
Einzelne Surrogate: encodeURIComponent('\uD800') wirft einen URIError. Wer Benutzereingaben kodiert, sollte das mit try…catch abfangen oder vorher mit String.prototype.isWellFormed() (ES2024) bzw. toWellFormed() bereinigen.
cause: Die Option cause gibt es erst seit ES2022 (Chrome 93, Firefox 91, Safari 15, Node.js 16.9). Ältere Umgebungen ignorieren sie ohne Fehlermeldung.
Nachrichten aus der Engine: Den Text von message legt bei automatisch geworfenen Fehlern die Engine fest, er unterscheidet sich je nach Browser. Für Programmlogik also instanceof oder name prüfen, nicht den Text.
Der Konstruktor URIError() selbst wird in allen Browsern und in Node.js unterstützt.

Siehe auch

URIError Error decodeURIComponent() encodeURIComponent() decodeURI() encodeURI() TypeError try...catch