IDBRequest: error — Ereignis · JavaScript-Referenz

Signatur

request.addEventListener("error", handler) / request.onerror = handler

Beschreibung

Das error-Ereignis wird an einem IDBRequest-Objekt ausgelöst, wenn die zugehörige IndexedDB-Operation nicht erfolgreich abgeschlossen werden kann. Typische Ursachen sind ein bereits vorhandener Schlüssel bei add() (ConstraintError), ein überschrittenes Speicherkontingent (QuotaExceededError) oder ein ungültiger Zustand der Transaktion. Den eigentlichen Fehler liest du über request.error bzw. event.target.error aus, ein DOMException-Objekt mit name und message.

Das Ereignis ist ein gewöhnliches Event. Es ist abbrechbar und steigt auf: vom IDBRequest über die IDBTransaction bis zur IDBDatabase. Du kannst Fehler also einzeln an der Anfrage behandeln oder zentral an der Datenbank- bzw. Transaktionsebene.

Wichtig ist das Standardverhalten: Wird das Ereignis nicht mit event.preventDefault() abgebrochen, bricht der Browser die gesamte Transaktion ab (abort), und alle bisherigen Änderungen darin werden zurückgerollt. Mit preventDefault() signalisierst du, dass der Fehler behandelt wurde und die Transaktion weiterlaufen darf.

Registrieren kannst du den Handler entweder mit addEventListener("error", handler) (mehrere Handler möglich, entfernbar per removeEventListener) oder über die Eigenschaft onerror (nur ein Handler, wird beim erneuten Zuweisen überschrieben).

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname, hier immer `"error"` (nur bei `addEventListener`).
$handler Pflicht	(event: Event) => void		Rückruffunktion, die das `Event`-Objekt erhält. Über `event.target.error` erreichst du die `DOMException`; `event.preventDefault()` verhindert den Abbruch der Transaktion.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once`, `capture` oder `signal` (nur bei `addEventListener`).

Rückgabewert

Typ

void

Beschreibung

Der Handler hat keinen relevanten Rückgabewert. Die Fehlerinformation steht in request.error (DOMException | null).

Beispiele

Doppelten Schlüssel 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');

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

  req.addEventListener('error', (event) => {
    const err = event.target.error;
    console.warn(`Fehler: ${err.name}`);
    // Fehler gilt als behandelt – Transaktion läuft weiter
    event.preventDefault();
  });

  tx.oncomplete = () => console.log('Transaktion abgeschlossen');
};

Fehler: ConstraintError Transaktion abgeschlossen

Fehler beim Öffnen per onerror-Eigenschaft

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

req.onerror = (event) => {
  // z. B. VersionError, wenn eine höhere Version bereits existiert
  console.error('Datenbank konnte nicht geöffnet werden:', event.target.error?.name);
};

req.onsuccess = () => {
  console.log('Datenbank geöffnet:', req.result.name);
};

Datenbank geöffnet: shop

Zentrale Fehlerbehandlung dank Bubbling

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

req.onsuccess = () => {
  const db = req.result;

  // Fängt alle aufsteigenden error-Ereignisse der Anfragen ab
  db.addEventListener('error', (event) => {
    console.error('IndexedDB-Fehler:', event.target.error?.name);
  });

  const tx = db.transaction('kunden', 'readwrite');
  tx.objectStore('kunden').add({ id: 1, name: 'Doppelt' });
  tx.onabort = () => console.log('Transaktion abgebrochen');
};

IndexedDB-Fehler: ConstraintError Transaktion abgebrochen

Handler wieder entfernen

const handleError = (event) => {
  console.error('Anfrage fehlgeschlagen:', event.target.error?.message);
};

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

req.onsuccess = () => {
  // Nach Erfolg nicht mehr benötigt
  req.removeEventListener('error', handleError);
  console.log('Listener entfernt');
};

Listener entfernt

// Wichtig · Fallstricke

Transaktionsabbruch: Ohne event.preventDefault() wird die komplette Transaktion abgebrochen, alle Schreibvorgänge darin werden verworfen. Das ist oft überraschend, wenn man nur eine einzelne fehlgeschlagene Anfrage erwartet.
Bubbling: Das Ereignis steigt zu IDBTransaction und IDBDatabase auf. Wer an mehreren Ebenen Handler registriert, bekommt denselben Fehler mehrfach gemeldet; bei Bedarf event.stopPropagation() verwenden.
Fehler auslesen: Das Ereignis selbst hat keine error-Eigenschaft. Nutze event.target.error bzw. request.error. Ein Zugriff auf request.result nach einem Fehler wirft einen InvalidStateError.
Handler nach dem Aufruf registrieren: Weil IndexedDB asynchron ist, kannst du Handler direkt nach dem Methodenaufruf im selben Task anhängen. Ereignisse, die schon ausgelöst wurden, bekommst du aber nicht nachträglich.
Privater Modus: Manche Browser, vor allem ältere Firefox- und Safari-Versionen, lassen indexedDB.open() im privaten Modus fehlschlagen oder beschränken den Speicher stark. Plane deshalb immer einen onerror-Zweig ein.
Kompatibilität: Wird von allen modernen Browsern unterstützt. In Web Workern ist das Ereignis ebenfalls verfügbar.

Siehe auch

IDBRequest IDBRequest: success IDBRequest.error IDBObjectStore.prototype.add() Event.prototype.preventDefault()