QuotaExceededError.quota — Eigenschaft · JavaScript-Referenz

Signatur

QuotaExceededError.quota

Beschreibung

Die Eigenschaft quota gehört zur Schnittstelle QuotaExceededError. Diese Schnittstelle erbt von DOMException. Browser werfen einen solchen Fehler, wenn eine Speicheroperation das Kontingent überschreiten würde, das das System festgelegt hat. Das passiert zum Beispiel bei localStorage.setItem(), in IndexedDB oder bei der Cache API. quota gibt dieses Kontingent in Bytes an, und zwar als Zahl (number).

Laut WebIDL ist die Eigenschaft als double? definiert, sie kann also auch leer sein. Legt der Browser das Kontingent nicht offen, etwa aus Datenschutzgründen oder weil es keinen festen Wert gibt, liefert die Eigenschaft null. Die ergänzende Eigenschaft requested gibt an, wie viele Bytes die fehlgeschlagene Operation insgesamt gebraucht hätte. Aus beiden Werten zusammen lässt sich ausrechnen, wie viel Speicher fehlt.

In der Praxis nutzt man quota vor allem zur Fehlerbehandlung und Diagnose. Man kann gezielt alte Cache-Einträge löschen, den Nutzer informieren oder die Werte an ein Monitoring-System melden. Früher war ein solcher Fehler nur ein DOMException mit name === "QuotaExceededError". Robuster Code prüft deshalb beide Varianten.

Rückgabewert

Typ

number | null

Beschreibung

Das Speicherkontingent in Bytes, das die Operation überschritten hätte. Ist das Kontingent unbekannt oder wird es nicht offengelegt, ist der Wert null. Die Eigenschaft ist schreibgeschützt.

Beispiele

localStorage-Überlauf abfangen und Kontingent auslesen

const speichern = (schluessel, wert) => {
  try {
    localStorage.setItem(schluessel, wert);
    return true;
  } catch (err) {
    // Neue Schnittstelle oder ältere DOMException-Variante
    const istQuotaFehler =
      (typeof QuotaExceededError !== 'undefined' && err instanceof QuotaExceededError) ||
      (err instanceof DOMException && err.name === 'QuotaExceededError');

    if (!istQuotaFehler) throw err;

    if (err.quota != null) {
      console.warn(`Kontingent von ${err.quota} Bytes überschritten.`);
    } else {
      console.warn('Speicherkontingent überschritten (Größe unbekannt).');
    }
    return false;
  }
};

// Etwa 10 MB Text – übersteigt das übliche localStorage-Limit
speichern('grosseDaten', 'x'.repeat(10 * 1024 * 1024));

Kontingent von 5242880 Bytes überschritten. (Der konkrete Wert hängt vom Browser ab.)

Fehlende Bytes aus quota und requested berechnen

const berichteSpeichermangel = (err) => {
  const { quota, requested } = err;
  if (quota == null || requested == null) {
    return 'Speicher voll – genaue Werte nicht verfügbar.';
  }
  const fehlendKB = ((requested - quota) / 1024).toFixed(1);
  return `Es fehlen ${fehlendKB} KB (Limit: ${quota} Bytes, benötigt: ${requested} Bytes).`;
};

// Fehler selbst erzeugen, z. B. für Tests
const fehler = new QuotaExceededError('Speicher voll', {
  quota: 1_048_576,
  requested: 1_310_720,
});

console.log(berichteSpeichermangel(fehler));

Es fehlen 256.0 KB (Limit: 1048576 Bytes, benötigt: 1310720 Bytes).

Konstruktor ohne Kontingent: quota ist null

const fehler = new QuotaExceededError('Cache voll');

console.log(fehler.name);      // Name des Fehlers
console.log(fehler.quota);     // nicht angegeben
console.log(fehler instanceof DOMException);

// Schreibgeschützt: die Zuweisung wird ignoriert (im Strict Mode: TypeError)
fehler.quota = 42;
console.log(fehler.quota);

QuotaExceededError null true null

// Wichtig · Fallstricke

Browser-Unterstützung: QuotaExceededError ist eine eigene Schnittstelle mit den Eigenschaften quota und requested. Sie wurde erst kürzlich standardisiert und ist noch nicht in allen Browsern verfügbar. Ältere Browser werfen stattdessen einen normalen DOMException mit name === "QuotaExceededError". Dort ist quota dann undefined. Vor dem Zugriff sollte man daher mit typeof QuotaExceededError !== 'undefined' prüfen, ob die Schnittstelle existiert. Für den Wert selbst deckt err.quota != null sowohl null als auch undefined ab.
Datenschutz: Browser dürfen das tatsächliche Kontingent verbergen oder nur einen gerundeten Wert melden, um Fingerprinting zu erschweren. Der Wert eignet sich für Diagnose und Fehlerbehandlung, aber nicht für eine exakte Speicherplanung. Dafür ist navigator.storage.estimate() besser geeignet.
Konstruktor-Prüfungen: Bei new QuotaExceededError(message, { quota, requested }) wirft der Browser einen RangeError, wenn quota oder requested negativ ist. Das gilt auch, wenn beide angegeben sind und requested kleiner als quota ist.
Die Einheit ist immer Bytes. Bei localStorage zählen Browser die Zeichen oft als UTF-16. Ein Zeichen belegt dann 2 Bytes, und die Rechnung weicht von der String-Länge ab.

Siehe auch

PerformanceTiming.requestStart QuotaExceededError.requested MediaError.code TextDecoder.fatal AudioEncoder.state