CKTIS / JavaScript
IDBRequest: request result and error
Learn when to read `result` and `error` in IndexedDB and how to tell an individual request's success from a transaction commit.
Version: ECMAScript 2024 and the current web platform; runtime support varies
Syntax
request.readyState; // "pending" or "done"
request.result; // operation-specific value on success; undefined on failure
request.error; // null on success; DOMException on failure
// Reading result or error while readyState is "pending" throws InvalidStateError.IDBRequest.result/error refers to two read-only properties on an IDBRequest instance. An IndexedDB request represents an asynchronous operation. It is not a Promise, so await request does not wait for the operation to finish. IndexedDB is a web-platform API, not part of ECMAScript 2024; availability depends on the runtime.
While request.readyState is "pending", reading either property throws a DOMException named InvalidStateError. The state "done" does not by itself mean success. Normally, read the result in the success handler. One exception: in the upgradeneeded handler of an indexedDB.open() request, result is already available for schema changes, even though the final success event has not fired yet.
On success, error is null and result depends on the operation: open() supplies an IDBDatabase connection, add() yields the stored record's key, and get() can yield undefined when no record matches the key. On error, result is undefined and error holds a DOMException. Inspect request.error.name to identify a failure such as ConstraintError. An undefined result alone does not mean failure. A try...catch around the API call catches synchronous exceptions, not failures reported later by an error event.
A successful write request does not mean its transaction has committed. Listen for complete to confirm the commit and abort to detect a rollback. A request error inside a transaction aborts it by default. For an expected error you can safely handle, calling event.preventDefault() in the request's error handler prevents that default abort, but does not make the failed request succeed.
Examples
<!doctype html>
<meta charset="utf-8">
<title>IDBRequest result and error</title>
<script>
(() => {
const { indexedDB, crypto } = window;
const name = `cktis-idbrequest-${crypto.randomUUID()}`;
const open = indexedDB.open(name, 1);
open.onupgradeneeded = () => open.result.createObjectStore("items");
open.onerror = () => console.error("open:", open.error.name);
open.onsuccess = () => {
const db = open.result;
const tx = db.transaction("items", "readwrite");
const store = tx.objectStore("items");
const cleanup = () => {
db.close();
const removal = indexedDB.deleteDatabase(name);
removal.onerror = () => console.error("cleanup:", removal.error.name);
};
tx.oncomplete = () => {
console.log("transaction: complete");
cleanup();
};
tx.onabort = () => {
console.error("transaction: abort", tx.error?.name);
cleanup();
};
const first = store.add("first", 1);
first.onsuccess = () => {
console.log(`first: result=${first.result}, error=${first.error}`);
const second = store.add("second", 1);
second.onerror = (event) => {
if (second.error.name === "ConstraintError") event.preventDefault();
console.log(`second: result=${second.result}, error=${second.error.name}`);
};
};
};
})();
</script>Result
first: result=1, error=null second: result=undefined, error=ConstraintError transaction: complete
Open the example as an HTML page served over HTTPS where IndexedDB and `crypto.randomUUID()` are available. Check the messages in the browser console. The second `add()` tries the same key. The handler prevents the default abort only for the expected `ConstraintError`, so the first write can commit. After the transaction ends, the code closes the connection and requests deletion of the test database.
Related lessons
- JavaScript · Lesson 20 · Intermediate · Version: 3
- JavaScript · Lesson 21 · Intermediate · Version: 3
Sources
- IDBRequest: result property
- IDBRequest: error property
- IDBRequest
- IDBRequest: readyState property
- IDBFactory: open() method
- IDBOpenDBRequest: upgradeneeded event
- IDBObjectStore: add() method
- IDBObjectStore: get() method
- IDBTransaction
- IDBTransaction: complete event
- IDBFactory: deleteDatabase() method
- Crypto: randomUUID() method