IDBRequest.error — Eigenschaft · JavaScript-Referenz

Signatur

get IDBRequest.error

Beschreibung

IDBRequest.error enthält den Grund, warum eine asynchrone IndexedDB-Operation gescheitert ist, z. B. add(), get(), put() oder indexedDB.open(). Die Eigenschaft ist schreibgeschützt. Wenn die Anforderung fehlschlägt, steht hier eine DOMException. Wenn sie erfolgreich war, ist der Wert null.

Normalerweise liest man die Eigenschaft im error-Handler der Anforderung aus, also über request.onerror oder request.addEventListener("error", …). Über error.name lässt sich die Fehlerursache unterscheiden. Häufige Werte sind:

ConstraintError: Ein Eindeutigkeits-Constraint wurde verletzt, etwa bei add() mit einem Schlüssel, den es schon gibt, oder bei einem eindeutigen Index.
QuotaExceededError: Der verfügbare Speicherplatz reicht nicht aus.
AbortError: Die Transaktion wurde abgebrochen, bevor die Anforderung fertig war.
VersionError: open() wurde mit einer kleineren Version als der vorhandenen aufgerufen.
DataError, NotFoundError, UnknownError: Der Schlüssel ist ungültig, ein Objektspeicher fehlt, oder es gab einen internen bzw. I/O-Fehler.

Die Eigenschaft darf erst gelesen werden, wenn die Anforderung abgeschlossen ist, also wenn readyState === "done" gilt. Ein Zugriff davor löst eine InvalidStateError-DOMException aus.

Rückgabewert

Typ

DOMException | null

Beschreibung

Eine DOMException mit name und message, wenn die Anforderung fehlgeschlagen ist, sonst null.

Beispiele

Doppelten Schlüssel bei add() erkennen

const openReq = indexedDB.open('shop', 1);

openReq.onupgradeneeded = () => {
  openReq.result.createObjectStore('kunden', { keyPath: 'id' });
};

openReq.onsuccess = () => {
  const db = openReq.result;
  const store = db.transaction('kunden', 'readwrite').objectStore('kunden');

  store.add({ id: 1, name: 'Anna' });
  const req = store.add({ id: 1, name: 'Bernd' }); // gleicher Schlüssel

  req.onerror = (event) => {
    console.log(req.error.name);
    // Standardverhalten verhindern, damit die Transaktion nicht abbricht
    event.preventDefault();
  };
};

ConstraintError

Fehler beim Öffnen der Datenbank auswerten

const req = indexedDB.open('meineDB', 1);

req.addEventListener('error', () => {
  const { name, message } = req.error;
  if (name === 'VersionError') {
    console.warn('Vorhandene Datenbank ist neuer:', message);
  } else {
    console.error(`Öffnen fehlgeschlagen (${name}): ${message}`);
  }
});

req.addEventListener('success', () => {
  console.log('Fehler:', req.error); // bei Erfolg null
});

Fehler: null

IDBRequest in ein Promise einpacken

const promisify = (request) =>
  new Promise((resolve, reject) => {
    request.onsuccess = () => resolve(request.result);
    request.onerror = () => reject(request.error);
  });

const speichern = async (db, eintrag) => {
  const store = db.transaction('notizen', 'readwrite').objectStore('notizen');
  try {
    return await promisify(store.put(eintrag));
  } catch (err) {
    if (err.name === 'QuotaExceededError') {
      console.error('Speicher voll – bitte alte Notizen löschen.');
    }
    throw err;
  }
};

// Wichtig · Fallstricke

InvalidStateError: Wenn man error liest, solange readyState noch "pending" ist, wird eine Ausnahme ausgelöst. Deshalb liest man die Eigenschaft nur in den success- oder error-Handlern.
Fehler wandern nach oben: Ein error-Ereignis bubbelt von der Anforderung zur IDBTransaction und dann zur IDBDatabase. Wenn niemand event.preventDefault() aufruft, wird die ganze Transaktion abgebrochen. Danach melden auch andere offene Anforderungen dieser Transaktion einen AbortError.
Veraltet: DOMError. Ältere Browser haben ein DOMError-Objekt statt einer DOMException geliefert. Vergleiche deshalb immer über error.name und nicht über instanceof oder numerische Codes.
Bei QuotaExceededError lohnt sich ein Blick auf navigator.storage.estimate() und navigator.storage.persist().
Im privaten Modus mancher Browser kann indexedDB.open() mit einem UnknownError oder InvalidStateError fehlschlagen. Plane dafür einen Ersatzweg ein.

Siehe auch

IDBRequest IDBRequest.result IDBRequest.readyState IDBTransaction.error DOMException MediaTrackSettings.cursor