IDBTransaction: error — Ereignis · JavaScript-Referenz

Signatur

transaction.addEventListener("error", handler)

Beschreibung

Das error-Ereignis tritt auf, wenn eine IDBRequest innerhalb einer Transaktion fehlschlägt, z. B. durch eine verletzte Eindeutigkeit (ConstraintError) bei add(). Das Ereignis wird zuerst auf der Anfrage ausgelöst und blubbert dann zur IDBTransaction und weiter zur IDBDatabase. Es ist ein einfaches Event mit bubbles: true und cancelable: true.

Mit einem Handler auf der Transaktion lassen sich Fehler zentral abfangen, statt an jede Anfrage einen eigenen onerror-Handler zu hängen. Den Handler registriert man mit transaction.addEventListener("error", handler) oder über die Eigenschaft transaction.onerror.

Wichtig: Wenn kein Handler event.preventDefault() aufruft, bricht die Transaktion standardmäßig ab. Alle Änderungen werden zurückgerollt, und anschließend wird das abort-Ereignis ausgelöst. Rufst du preventDefault() auf (auf der Anfrage oder in einem Handler weiter oben), läuft die Transaktion weiter und kann trotz des einzelnen Fehlers erfolgreich mit complete abschließen.

Das auslösende Objekt ist event.target, also die fehlgeschlagene IDBRequest. Das Fehlerobjekt steht in event.target.error als DOMException bereit.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"error"`.
$handler Pflicht	(event: Event) => void		Callback mit einem `Event`. `event.target` ist die fehlgeschlagene `IDBRequest`, `event.target.error` die `DOMException`.
$options	boolean \| AddEventListenerOptions	false	Optionen wie `once`, `capture` oder `signal`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein Event, das die Transaktion abbrechen kann, wenn es nicht mit preventDefault() abgebrochen wird.

Beispiele

Fehler zentral mit addEventListener abfangen

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');

  tx.addEventListener('error', (event) => {
    const err = event.target.error;
    console.log(`Transaktionsfehler: ${err.name}`);
  });

  tx.addEventListener('abort', () => console.log('Transaktion abgebrochen'));

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

Transaktionsfehler: ConstraintError Transaktion abgebrochen

Fehler tolerieren mit preventDefault() über onerror

const importiereKunden = (db, kunden) => new Promise((resolve, reject) => {
  const tx = db.transaction('kunden', 'readwrite');
  const store = tx.objectStore('kunden');
  let uebersprungen = 0;

  tx.onerror = (event) => {
    if (event.target.error?.name === 'ConstraintError') {
      event.preventDefault(); // Transaktion NICHT abbrechen
      uebersprungen++;
    }
  };

  tx.oncomplete = () => resolve(uebersprungen);
  tx.onabort = () => reject(tx.error);

  kunden.forEach((k) => store.add(k));
});

// Verwendung (db ist eine geöffnete IDBDatabase):
// const n = await importiereKunden(db, [{ id: 1 }, { id: 1 }, { id: 2 }]);
// console.log(`${n} Duplikat(e) übersprungen`);

1 Duplikat(e) übersprungen

Handler wieder entfernen

const tx = db.transaction('kunden', 'readwrite');

const onTxError = (event) => {
  console.error('Fehler:', event.target.error.message);
};

tx.addEventListener('error', onTxError);

// später, z. B. wenn ein anderes Modul übernimmt:
tx.removeEventListener('error', onTxError);

// alternativ über die Eigenschaft zurücksetzen:
tx.onerror = null;

// Wichtig · Fallstricke

Standardmäßiger Abbruch: Ohne event.preventDefault() wird die gesamte Transaktion zurückgerollt, auch bereits erfolgreiche Schreibvorgänge. Danach folgt abort, nicht complete.
Bubbling: Ruft ein Handler an der Anfrage event.stopPropagation() auf, erreicht das Ereignis die Transaktion nicht mehr. Der Abbruch passiert trotzdem, solange niemand preventDefault() aufruft.
event.target vs. event.currentTarget: target ist die fehlgeschlagene IDBRequest, currentTarget die Transaktion. transaction.error ist erst nach einem Abbruch gesetzt.
Nicht jeder Abbruch löst error aus: Ein manuelles transaction.abort() oder ein QuotaExceededError beim Commit meldet sich nur über abort. Deshalb sollte man immer auch abort abhören.
Browser-Kompatibilität: In allen modernen Browsern unterstützt. Im privaten Modus älterer Firefox-Versionen war IndexedDB teils nicht verfügbar.

Siehe auch

IDBTransaction IDBTransaction.error IDBTransaction.prototype.abort() Event.prototype.preventDefault() IDBTransaction: abort