QuotaExceededError.requested — Eigenschaft · JavaScript-Referenz

Signatur

QuotaExceededError.requested

Beschreibung

Die Eigenschaft requested einer QuotaExceededError-Instanz enthält die Menge an Speicher in Bytes, die der fehlgeschlagene Vorgang belegen wollte, etwa beim Schreiben in localStorage, in IndexedDB oder in die Cache API. Zusammen mit quota, dem verfügbaren Kontingent, lässt sich so abschätzen, wie weit das Limit überschritten wurde.

QuotaExceededError ist eine eigene Unterklasse von DOMException. Früher gab es nur eine DOMException mit dem name "QuotaExceededError", die keine Mengenangaben enthielt. Die neue Klasse behält diesen Namen bei, damit bestehender Code weiterhin funktioniert, liefert aber zusätzlich quota und requested.

Typische Anwendungsfälle sind aussagekräftige Fehlermeldungen („Es werden 2,3 MB benötigt, erlaubt sind 5 MB“), Protokollierung und Telemetrie, oder die Entscheidung, ob man alte Daten löscht und den Schreibvorgang wiederholt oder ob der Datensatz schlicht zu groß ist.

Die Eigenschaft lässt sich nur lesen. Setzen kann man sie allein beim Erzeugen über den Konstruktor: new QuotaExceededError(message, { quota, requested }).

Rückgabewert

Typ

number | null (laut MDN auch undefined)

Beschreibung

Die angeforderte Menge in Bytes als nicht-negative Zahl. Ist die Angabe nicht verfügbar, liefert die Eigenschaft laut WebIDL-Spezifikation null. MDN nennt dafür undefined.

Beispiele

localStorage-Überlauf mit Mengenangabe auswerten

const saveDraft = (key, data) => {
  try {
    localStorage.setItem(key, JSON.stringify(data));
    return true;
  } catch (err) {
    const isQuota = err instanceof DOMException && err.name === 'QuotaExceededError';
    if (!isQuota) throw err;

    // requested und quota gibt es nur bei der neuen Unterklasse
    if (err.requested != null && err.quota != null) {
      const kb = (n) => (n / 1024).toFixed(1);
      console.warn(`Speicher voll: ${kb(err.requested)} KB angefordert, Kontingent ${kb(err.quota)} KB`);
    } else {
      console.warn('Speicher voll (keine Mengenangaben verfügbar)');
    }
    return false;
  }
};

saveDraft('entwurf', { text: 'x'.repeat(10_000_000) });

Speicher voll: 19531.3 KB angefordert, Kontingent 5120.0 KB (Werte browserabhängig; in älteren Browsern: "Speicher voll (keine Mengenangaben verfügbar)")

Fehler mit Angaben selbst erzeugen (z. B. in einer eigenen Speicherschicht)

const QUOTA = 1024 * 1024; // 1 MB eigenes Limit
let used = 900 * 1024;

const reserve = (bytes) => {
  if (used + bytes > QUOTA) {
    throw new QuotaExceededError('Eigenes Kontingent überschritten', {
      quota: QUOTA,
      requested: bytes
    });
  }
  used += bytes;
};

try {
  reserve(200 * 1024);
} catch (err) {
  console.log(err.name, err.requested, err.quota);
  console.log(err instanceof DOMException);
}

QuotaExceededError 204800 1048576 true

Entscheiden: Aufräumen oder aufgeben

const putInCache = async (request, response) => {
  const cache = await caches.open('assets-v1');
  try {
    await cache.put(request, response.clone());
  } catch (err) {
    if (err?.name !== 'QuotaExceededError') throw err;

    const { requested, quota } = err;
    if (requested != null && quota != null && requested > quota) {
      // Selbst ein leerer Speicher würde nicht reichen
      console.error('Eintrag ist größer als das gesamte Kontingent, wird übersprungen.');
      return;
    }
    // Sonst: alte Caches löschen und einmal erneut versuchen
    await caches.delete('assets-v0');
    await cache.put(request, response);
  }
};

// Wichtig · Fallstricke

Browser-Kompatibilität: Die Klasse QuotaExceededError und ihre Eigenschaften sind sehr neu. In älteren Browsern wird nur eine einfache DOMException mit name === "QuotaExceededError" geworfen, und requested existiert dort nicht. Prüfe den Fehler deshalb über err.name statt über instanceof QuotaExceededError, denn in alten Umgebungen gibt es die Klasse gar nicht, und schon der Verweis darauf löst einen ReferenceError aus.
Fehlende Angabe: Laut Spezifikation steht dann null in der Eigenschaft, MDN nennt undefined, und in alten Browsern fehlt die Eigenschaft ganz. Eine lockere Prüfung mit err.requested != null deckt alle drei Fälle ab.
Datenschutz: Browser dürfen die Angabe bewusst weglassen oder ungenau machen, damit man darüber keine Rückschlüsse auf den Speicher oder die Speicherbelegung des Nutzers ziehen kann (Fingerprinting). Verlasse dich also nicht darauf, dass ein Wert vorhanden ist.
Einheit und Genauigkeit: Der Wert wird in Bytes angegeben. Bei localStorage hängt er davon ab, wie der Browser Zeichen zählt (z. B. UTF-16, also 2 Bytes pro Zeichen), und kann daher von JSON.stringify(data).length abweichen.
Konstruktor-Prüfung: Übergibst du beim Erzeugen negative Werte oder ein requested, das kleiner als quota ist, wirft der Konstruktor einen RangeError.
Für eine Vorabprüfung, bevor ein Fehler entsteht, eignet sich navigator.storage.estimate() besser.

Siehe auch

QuotaExceededError QuotaExceededError.quota DOMException StorageManager.estimate() Storage.setItem() Cache.put() VideoTrackGenerator.muted