IDBTransaction.error — Eigenschaft · JavaScript-Referenz

Signatur

IDBTransaction.error

Beschreibung

Die schreibgeschützte Eigenschaft error einer IDBTransaction enthält eine DOMException, die erklärt, warum eine Transaktion abgebrochen wurde. Man liest sie typischerweise im abort- oder error-Handler der Transaktion aus, um den Fehler zu protokollieren, dem Nutzer eine Meldung anzuzeigen oder eine Wiederholung anzustoßen.

Der Wert ist null, solange die Transaktion noch läuft, wenn sie erfolgreich abgeschlossen wurde (complete) oder wenn sie bewusst per transaction.abort() abgebrochen wurde. Nur wenn die Transaktion durch einen Fehler abbricht, ist ein Fehlerobjekt gesetzt.

Typische Werte von error.name:

ConstraintError – eine Anfrage verletzte eine Bedingung (z. B. doppelter Schlüssel bei add() oder ein unique-Index) und der Fehler wurde nicht mit event.preventDefault() abgefangen.
QuotaExceededError – der verfügbare Speicherplatz des Ursprungs ist erschöpft.
UnknownError – ein interner Fehler, z. B. ein I/O-Problem beim Schreiben auf die Festplatte.
AbortError – die Transaktion wurde von außen abgebrochen, etwa weil die Datenbankverbindung geschlossen wurde.

Schlägt eine einzelne Anfrage fehl, steigt ihr error-Ereignis zur Transaktion auf. Ohne preventDefault() wird die Transaktion abgebrochen und transaction.error übernimmt den Fehler der auslösenden Anfrage.

Rückgabewert

Typ

DOMException | null

Beschreibung

Eine DOMException mit name und message der Abbruchursache oder null, wenn kein Fehler aufgetreten ist, die Transaktion noch aktiv ist oder per abort() abgebrochen wurde.

Beispiele

Fehlerursache im abort-Handler auslesen

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

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

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

  store.add({ id: 1, name: 'Anna' });
  store.add({ id: 1, name: 'Doppelt' }); // gleicher Schlüssel -> ConstraintError

  tx.oncomplete = () => console.log('Gespeichert, error =', tx.error);
  tx.onabort = () => {
    console.log('Abgebrochen:', tx.error?.name);
  };
};

Abgebrochen: ConstraintError

Bewusster Abbruch: error bleibt null

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

req.onsuccess = () => {
  const tx = req.result.transaction('kunden', 'readwrite');
  tx.objectStore('kunden').put({ id: 2, name: 'Ben' });

  tx.onabort = () => {
    // Manueller Abbruch per abort() setzt keinen Fehler
    console.log('error:', tx.error);
  };

  tx.abort();
};

error: null

Transaktion als Promise mit sauberer Fehlerweitergabe

const txDone = (tx) =>
  new Promise((resolve, reject) => {
    tx.oncomplete = () => resolve();
    tx.onerror = () => reject(tx.error);
    tx.onabort = () =>
      reject(tx.error ?? new DOMException('Transaktion abgebrochen', 'AbortError'));
  });

const speichern = async (db, datensaetze) => {
  const tx = db.transaction('kunden', 'readwrite');
  const store = tx.objectStore('kunden');
  datensaetze.forEach((d) => store.put(d));

  try {
    await txDone(tx);
    console.log('Alle Datensätze gespeichert');
  } catch (err) {
    if (err.name === 'QuotaExceededError') {
      console.warn('Speicher voll – bitte alte Daten löschen.');
    } else {
      console.error(`${err.name}: ${err.message}`);
    }
  }
};

Alle Datensätze gespeichert

// Wichtig · Fallstricke

null heißt nicht immer Erfolg: Auch nach tx.abort() ist error null. Ob eine Transaktion erfolgreich war, zeigt zuverlässig nur das complete-Ereignis.
Fehler abfangen verhindert den Abbruch: Ruft man im error-Handler einer Anfrage event.preventDefault() auf, läuft die Transaktion weiter und transaction.error bleibt null.
Zeitpunkt: Lies die Eigenschaft erst in onabort/onerror aus. Solange die Transaktion aktiv ist, ist der Wert null. Ältere Spezifikationen warfen hier einen InvalidStateError.
Kompatibilität: Ältere Browser lieferten statt einer DOMException ein DOMError-Objekt. Beide haben name, daher ist der Vergleich über error.name am robustesten. Heute unterstützen alle modernen Browser die Eigenschaft. Sie steht auch in Web Workern zur Verfügung.
QuotaExceededError kann auch im privaten Modus auftreten, weil Browser dort oft deutlich weniger Speicher erlauben.

Siehe auch

IDBTransaction IDBTransaction.prototype.abort() IDBRequest.error DOMException IDBTransaction.db