Signatur
Beschreibung
Die Schnittstelle QuotaExceededError steht für einen Fehler, der auftritt, wenn eine Schreib- oder Speicheroperation mehr Platz braucht, als der Browser der Herkunft (Origin) zugesteht. Typische Auslöser sind localStorage.setItem(), sessionStorage.setItem(), Transaktionen in IndexedDB, Cache.put(), das Origin Private File System oder crypto.getRandomValues() mit einem zu großen Array (mehr als 65.536 Byte).
Früher gab es für diesen Fall nur eine gewöhnliche DOMException mit name === "QuotaExceededError" (alter Fehlercode 22). Inzwischen ist QuotaExceededError in WebIDL als eigene Unterklasse von DOMException festgelegt. Sie hat zwei zusätzliche Eigenschaften: quota (das geltende Kontingent in Byte) und requested (die angeforderte Menge in Byte). Beide dürfen null sein, wenn der Browser die Werte nicht nennen kann oder aus Datenschutzgründen nicht nennen will.
Weil die neue Klasse von DOMException erbt und den Namen "QuotaExceededError" behält, funktioniert die Prüfung err instanceof DOMException && err.name === "QuotaExceededError" in alten und neuen Browsern gleich. Deshalb solltest du diese Prüfung verwenden und nicht allein instanceof QuotaExceededError.
Fang diesen Fehler immer dann ab, wenn deine Anwendung Daten auf dem Client zwischenspeichert. Reagieren kannst du zum Beispiel, indem du alte Einträge löschst, auf den Arbeitsspeicher ausweichst oder mit navigator.storage.persist() dauerhaften Speicher anforderst.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $message | string | "" | Konstruktor-Parameter: lesbare Fehlermeldung, später über error.message abrufbar. |
| $options | { quota?: number, requested?: number } | {} | Konstruktor-Parameter: Objekt mit den optionalen Zahlen quota (Kontingent in Byte) und requested (angeforderte Menge in Byte). Negative Werte oder requested < quota lösen einen RangeError aus. |
| $quota | number | null | null | Eigenschaft (nur lesbar): das Speicherkontingent in Byte, sofern bekannt. |
| $requested | number | null | null | Eigenschaft (nur lesbar): die Menge in Byte, die die fehlgeschlagene Operation angefordert hat, sofern bekannt. |
| $name | string | "QuotaExceededError" | Von DOMException geerbt; immer "QuotaExceededError". |
Rückgabewert
new QuotaExceededError(message, options) gibt eine neue Fehlerinstanz zurück, die von DOMException und Error erbt.Beispiele
localStorage sicher beschreiben und bei vollem Speicher aufräumen
const istQuotaFehler = (err) =>
err instanceof DOMException && err.name === 'QuotaExceededError';
const speichern = (key, wert) => {
try {
localStorage.setItem(key, JSON.stringify(wert));
return true;
} catch (err) {
if (istQuotaFehler(err)) {
console.warn('Speicher voll – lösche Cache-Einträge');
Object.keys(localStorage)
.filter((k) => k.startsWith('cache:'))
.forEach((k) => localStorage.removeItem(k));
try {
localStorage.setItem(key, JSON.stringify(wert));
return true;
} catch {
return false; // immer noch zu groß
}
}
throw err; // anderer Fehler
}
};
// Absichtlich zu großer Wert (~20 MB)
console.log(speichern('riesig', 'x'.repeat(20 * 1024 * 1024)));Instanz erzeugen und Eigenschaften auslesen
if (typeof QuotaExceededError === 'function') {
const err = new QuotaExceededError('Upload-Puffer voll', {
quota: 5_000_000,
requested: 7_500_000,
});
console.log(err.name); // "QuotaExceededError"
console.log(err.message); // "Upload-Puffer voll"
console.log(err.quota, err.requested); // 5000000 7500000
console.log(err instanceof DOMException); // true
} else {
// Fallback für ältere Browser
const err = new DOMException('Upload-Puffer voll', 'QuotaExceededError');
console.log(err.name, err.code); // "QuotaExceededError" 22
}Cache-API: Fehler abfangen und Speicherstand prüfen
const inCacheLegen = async (url) => {
const cache = await caches.open('assets-v1');
try {
await cache.add(url);
} catch (err) {
if (err instanceof DOMException && err.name === 'QuotaExceededError') {
const { usage, quota } = await navigator.storage.estimate();
console.warn(
`Kontingent erschöpft: ${(usage / 1e6).toFixed(1)} MB von ${(quota / 1e6).toFixed(1)} MB belegt`
);
// Dauerhaften Speicher anfragen, damit der Browser weniger aggressiv räumt
const persistent = await navigator.storage.persist();
console.log('Persistenter Speicher:', persistent);
return;
}
throw err;
}
};
await inCacheLegen('/videos/intro.mp4');crypto.getRandomValues() mit zu großem Puffer
try {
crypto.getRandomValues(new Uint8Array(70_000)); // Grenze: 65.536 Byte
} catch (err) {
console.log(err.name);
}