Signatur
Beschreibung
URIError ist eine eingebaute Fehlerklasse, die von Error erbt und speziell für Fehler bei der URI-Verarbeitung vorgesehen ist. Sie wird automatisch von den globalen Funktionen decodeURI(), decodeURIComponent(), encodeURI() und encodeURIComponent() ausgelöst, wenn diese eine fehlerhafte Eingabe erhalten – zum Beispiel eine unvollständige Percent-Encoding-Sequenz wie % ohne gültige Hex-Ziffern.
Der häufigste Auslöser ist das Übergeben einer Zeichenkette mit beschädigten oder unvollständigen Escape-Sequenzen an decodeURIComponent(). Da diese Funktion erwartet, dass alle %xx-Sequenzen gültige UTF-8-Codierungen darstellen, führt ein falsch codierter String unweigerlich zu einem URIError.
Eigene URIError-Instanzen können mit new URIError(message) erzeugt werden. Dies ist nützlich, wenn man in eigenen URI-Verarbeitungsfunktionen semantisch passende Fehlertypen werfen möchte. Über instanceof URIError lässt sich im catch-Block zwischen verschiedenen Fehlerklassen unterscheiden.
- name: Immer
"URIError" - message: Optionale Fehlerbeschreibung als Zeichenkette
- stack: Stack-Trace (nicht standardisiert, aber in allen gängigen Engines verfügbar)
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $message | string | "" | Optionale, menschenlesbare Fehlerbeschreibung, die als message-Eigenschaft der Instanz gespeichert wird. |
| $options | { cause?: any } | Optionales Optionsobjekt (ab ES2022). Die cause-Eigenschaft ermöglicht es, einen zugrunde liegenden Fehler als Ursache zu verknüpfen (error.cause). |
Rückgabewert
URIError-Instanz mit den Eigenschaften name ("URIError"), message und ggf. stack.Beispiele
URIError beim Decodieren einer ungültigen URI abfangen
const malformedURI = '%';
try {
const decoded = decodeURIComponent(malformedURI);
console.log(decoded);
} catch (error) {
if (error instanceof URIError) {
console.error('Ungültige URI:', error.message);
// Fallback: Eingabe unverändert verwenden
console.log('Fallback:', malformedURI);
} else {
throw error; // Unbekannte Fehler weiterwerfen
}
}Eigene URI-Validierungsfunktion mit URIError
/**
* Decodiert einen URI-Komponenten-String sicher.
* Wirft einen URIError mit aussagekräftiger Nachricht bei Fehler.
*/
const safeDecodeURIComponent = (value) => {
if (typeof value !== 'string') {
throw new TypeError('Erwartet einen String');
}
try {
return decodeURIComponent(value);
} catch (error) {
throw new URIError(
`Ungültiger URI-Komponenten-String: "${value}"`,
{ cause: error }
);
}
};
// Gültige Eingabe
console.log(safeDecodeURIComponent('Hello%20World')); // "Hello World"
// Ungültige Eingabe
try {
safeDecodeURIComponent('%E0%A4%A');
} catch (e) {
console.error(e.name + ':', e.message);
console.error('Ursache:', e.cause?.message);
}// Wichtig · Fallstricke
Typische Fehlerquellen: URIError tritt häufig auf, wenn URL-Parameter aus externen Quellen (Formulare, Query-Strings, Datenbanken) ohne Validierung direkt an decodeURIComponent() übergeben werden. Benutzereingaben sollten daher immer in einem try/catch-Block decodiert werden.
Unterschied zu anderen Fehlerklassen: Im Gegensatz zu TypeError (falscher Typ) oder RangeError (Wertebereich überschritten) signalisiert URIError ausschließlich Probleme mit der Struktur eines URI-Strings. Der Name der Instanz ist immer "URIError", was eine zuverlässige Unterscheidung per instanceof oder error.name erlaubt.
Browser-Kompatibilität: URIError ist seit ES3 Teil des Standards und wird in allen gängigen Umgebungen (Browser, Node.js, Deno) vollständig unterstützt. Die cause-Option im Konstruktor ist ab ES2022 / Node.js 16.9+ verfügbar.