From 98044e8d9ad3046a90bc573dd83ebf8cfd89fe76 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Sun, 1 Dec 2024 16:14:09 +0000 Subject: [PATCH 1/5] Add docs for improved error reporting for large value read failures --- files/en-us/web/api/idbrequest/error/index.md | 52 +++++++++++++++---- 1 file changed, 41 insertions(+), 11 deletions(-) diff --git a/files/en-us/web/api/idbrequest/error/index.md b/files/en-us/web/api/idbrequest/error/index.md index 03ec2ef4a521628..8c4c657ba154f68 100644 --- a/files/en-us/web/api/idbrequest/error/index.md +++ b/files/en-us/web/api/idbrequest/error/index.md @@ -14,22 +14,52 @@ request. ## Value -A {{domxref("DOMException")}} or `null` if there is no error. The following error names are returned -in the exception object: +A {{domxref("DOMException")}} or `null` if there is no error. The following error names can be returned +in the exception object, depending on what caused the error. + +### Transaction errors - `AbortError` - - : If you abort the transaction, then all requests still in progress receive this error. + - : Thrown if you abort the transaction, then all requests still in progress receive this error. +- `ReadOnlyError` + - : Thrown if the mutating operation was attempted in a read-only transaction. +- `SyntaxError` + - : Thrown in the `keyPath` argument contains an invalid key path. +- `TransactionInactiveError` + - : Thrown if a request was placed against a transaction which is currently not active, or which is finished. + +### Data integrity errors + - `ConstraintError` - - : If you insert data that doesn't conform to a constraint. - It's an exception type for creating stores and indexes. - You get this error, for example, if you try to add a new key that already exists in the record. + - : Thrown if you insert data that doesn't conform to a constraint when creating stores and indexes. + For example, you will get this error if you try to add a new key that already exists in the record. +- `DataError` + - : Thrown if data provided to an operation does not meet requirements. +- `DataCloneError` + - : Thrown if the data being stored could not be cloned by the internal structured cloning algorithm. +- `InvalidAccessError` + - : Thrown if an invalid operation was performed on an object. +- `InvalidStateError` + - : Thrown if an operation was called on an object on which it is not allowed or at a time when it is not allowed, or if a request is made on a source object that has been deleted or removed. For example, if a result is accessed before the corresponding request is completed. - `QuotaExceededError` - - : If you run out of disk quota and the user declined to grant you more space. -- `UnknownError` - - : If the operation failed for reasons unrelated to the database itself. - A failure due to disk IO errors is such an example. + - : Thrown if you run out of disk quota and the user declined to grant the application more space. - `VersionError` - - : If you try to open a database with a version lower than the one it already has. + - : Thrown if you try to open a database with a version lower than the one it already has. + +### Large value read failure errors + +Large IndexedDB values are not stored directly in the underlying database; instead, they are stored as separate files that are accessed via a reference stored in the database. This category of errors can occur due to transient causes such as low memory and unrecoverable causes such as source blob files being deleted. Separate blob files containing IndexedDB data can end up being deleted because they show up as opaque files to users when they are using disk space recovery programs. + +Possible corrective actions for such unrecoverable cases might include notifying the user, deleting the entry from the DB, then attempting to re-fetch the data from the server. + +Errors in this caregory are as follows. More recent browser versions have changed the error types thrown and improved the error messages to help developers distinguish between transient and unrecoverable cases. + +- `NotFoundError` or `NotReadableError` + - : Thrown for unrecoverable errors. +- `DataError` or `UnknownError` + - : Thrown for transient errors, including general disk IO errors. + +### Related errors In addition to the error codes sent to the {{ domxref("IDBRequest") }} object, asynchronous operations can also raise exceptions. The list describes problems that From c6becc7a913ef90c781ab0804fe222e03fdadcda Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Tue, 3 Dec 2024 11:40:39 +0000 Subject: [PATCH 2/5] Fixed for inexorabletash review comments --- files/en-us/web/api/idbcursor/key/index.md | 5 ++ .../web/api/idbcursor/primarykey/index.md | 5 ++ .../en-us/web/api/idbcursor/request/index.md | 5 ++ .../idbdatabase/createobjectstore/index.md | 14 +++-- .../web/api/idbobjectstore/clear/index.md | 2 + files/en-us/web/api/idbrequest/error/index.md | 59 ++++++------------- 6 files changed, 43 insertions(+), 47 deletions(-) diff --git a/files/en-us/web/api/idbcursor/key/index.md b/files/en-us/web/api/idbcursor/key/index.md index 65d3c5d898c9980..947256dabeee47a 100644 --- a/files/en-us/web/api/idbcursor/key/index.md +++ b/files/en-us/web/api/idbcursor/key/index.md @@ -17,6 +17,11 @@ key can be any data type. A value of any type. +### Exceptions + +- `InvalidStateError` {{domxref("DOMException")}} + - : Thrown if the cursor is advancing or has finished. + ## Examples In this simple fragment we create a transaction, retrieve an object store, then use a diff --git a/files/en-us/web/api/idbcursor/primarykey/index.md b/files/en-us/web/api/idbcursor/primarykey/index.md index 6d44c3b82c876e9..5fa13ceaf39bc48 100644 --- a/files/en-us/web/api/idbcursor/primarykey/index.md +++ b/files/en-us/web/api/idbcursor/primarykey/index.md @@ -17,6 +17,11 @@ undefined. The cursor's primary key can be any data type. A value of any data type. +### Exceptions + +- `InvalidStateError` {{domxref("DOMException")}} + - : Thrown if the cursor is advancing or has finished. + ## Examples In this simple fragment we create a transaction, retrieve an object store, then use a diff --git a/files/en-us/web/api/idbcursor/request/index.md b/files/en-us/web/api/idbcursor/request/index.md index 9527caeec4a36b8..7a42cdce60f1bfd 100644 --- a/files/en-us/web/api/idbcursor/request/index.md +++ b/files/en-us/web/api/idbcursor/request/index.md @@ -14,6 +14,11 @@ The **`request`** read-only property of the {{domxref("IDBCursor")}} interface r An {{domxref("IDBRequest")}} object instance. +### Exceptions + +- `InvalidStateError` {{domxref("DOMException")}} + - : Thrown if the cursor is already advancing. + ## Examples When you open a cursor, the `request` property is then available on that cursor object, to tell you what request object the cursor originated from. For example: diff --git a/files/en-us/web/api/idbdatabase/createobjectstore/index.md b/files/en-us/web/api/idbdatabase/createobjectstore/index.md index d2205109fee13db..2ad15379f933880 100644 --- a/files/en-us/web/api/idbdatabase/createobjectstore/index.md +++ b/files/en-us/web/api/idbdatabase/createobjectstore/index.md @@ -54,20 +54,22 @@ A new {{domxref("IDBObjectStore")}}. This method may raise a {{domxref("DOMException")}} with a `name` of one of the following types: +- `ConstraintError` {{domxref("DOMException")}} + - : Thrown if an object store with the given name (based on a case-sensitive comparison) + already exists in the connected database. +- `InvalidAccessError` {{domxref("DOMException")}} + - : Thrown if `autoIncrement` is set to true and `keyPath` is + either an empty string or an array containing an empty string. - `InvalidStateError` {{domxref("DOMException")}} - : Thrown if the method was not called from a `versionchange` transaction callback. +- `SyntaxError` + - : Thrown if the `keyPath` option contains an invalid key path. - `TransactionInactiveError` {{domxref("DOMException")}} - : Thrown if a request is made on a source database that does not exist (for example, when the database has been deleted or removed). In Firefox previous to version 41, an `InvalidStateError` was raised in this case as well, which was misleading; this has now been fixed (see [Firefox bug 1176165](https://bugzil.la/1176165)). -- `ConstraintError` {{domxref("DOMException")}} - - : Thrown if an object store with the given name (based on a case-sensitive comparison) - already exists in the connected database. -- `InvalidAccessError` {{domxref("DOMException")}} - - : Thrown if `autoIncrement` is set to true and `keyPath` is - either an empty string or an array containing an empty string. ## Examples diff --git a/files/en-us/web/api/idbobjectstore/clear/index.md b/files/en-us/web/api/idbobjectstore/clear/index.md index 4ba1dc7c6366722..47a62ee95dde6b9 100644 --- a/files/en-us/web/api/idbobjectstore/clear/index.md +++ b/files/en-us/web/api/idbobjectstore/clear/index.md @@ -36,6 +36,8 @@ If the operation is successful, the value of the request's {{domxref("IDBRequest ### Exceptions +- `InvalidStateError` {{domxref("DOMException")}} + - : Thrown if the object store has been deleted. - `ReadOnlyError` {{domxref("DOMException")}} - : Thrown if the transaction associated with this operation is in read-only [mode](/en-US/docs/Web/API/IDBTransaction/mode). - `TransactionInactiveError` {{domxref("DOMException")}} diff --git a/files/en-us/web/api/idbrequest/error/index.md b/files/en-us/web/api/idbrequest/error/index.md index 8c4c657ba154f68..c85de2a0eb23b23 100644 --- a/files/en-us/web/api/idbrequest/error/index.md +++ b/files/en-us/web/api/idbrequest/error/index.md @@ -10,62 +10,38 @@ browser-compat: api.IDBRequest.error The **`error`** read-only property of the {{domxref("IDBRequest")}} interface returns the error in the event of an unsuccessful -request. +request. If the request is not completed, the error is not available and an `InvalidStateError` exception is +thrown. ## Value -A {{domxref("DOMException")}} or `null` if there is no error. The following error names can be returned -in the exception object, depending on what caused the error. +A {{domxref("DOMException")}} or `null` if there is no error. The exception object will have one of the following names, depending on what caused the error. -### Transaction errors +These errors are asynchronous, meaning that they can't be handled via [`try...catch`](/en-US/docs/Web/JavaScript/Reference/Statements/try...catch). However, if an `IDBRequest` has an {{domxref("IDBRequest.error", "error")}} event handler assigned, you can still inspect such errors by querying the request's `error` property via the event object, for example [`event.target.error.name`](/en-US/docs/Web/API/DOMException/name) or [`event.target.error.message`](/en-US/docs/Web/API/DOMException/message). - `AbortError` - - : Thrown if you abort the transaction, then all requests still in progress receive this error. -- `ReadOnlyError` - - : Thrown if the mutating operation was attempted in a read-only transaction. -- `SyntaxError` - - : Thrown in the `keyPath` argument contains an invalid key path. -- `TransactionInactiveError` - - : Thrown if a request was placed against a transaction which is currently not active, or which is finished. - -### Data integrity errors - + - : If you abort the transaction, then all requests still in progress receive this error. - `ConstraintError` - - : Thrown if you insert data that doesn't conform to a constraint when creating stores and indexes. + - : Received if you insert data that doesn't conform to a constraint when creating stores and indexes. For example, you will get this error if you try to add a new key that already exists in the record. -- `DataError` - - : Thrown if data provided to an operation does not meet requirements. -- `DataCloneError` - - : Thrown if the data being stored could not be cloned by the internal structured cloning algorithm. -- `InvalidAccessError` - - : Thrown if an invalid operation was performed on an object. -- `InvalidStateError` - - : Thrown if an operation was called on an object on which it is not allowed or at a time when it is not allowed, or if a request is made on a source object that has been deleted or removed. For example, if a result is accessed before the corresponding request is completed. +- `DataError` or `UnknownError` + - : Received for transient read failure errors, including general disk IO errors. See "Large value read failure errors" below for more details. +- `NotFoundError` or `NotReadableError` + - : Received for unrecoverable read failure errors. See "Large value read failure errors" below for more details. - `QuotaExceededError` - - : Thrown if you run out of disk quota and the user declined to grant the application more space. + - : Received if the application runs out of disk quota. In some cases, browsers prompt the user for more space, and the error is received if they decline the request. In other cases, the browser uses heuristics to determine whether more space can be assigned. - `VersionError` - - : Thrown if you try to open a database with a version lower than the one it already has. + - : If you try to open a database with a version lower than the one it already has, this error is received. ### Large value read failure errors -Large IndexedDB values are not stored directly in the underlying database; instead, they are stored as separate files that are accessed via a reference stored in the database. This category of errors can occur due to transient causes such as low memory and unrecoverable causes such as source blob files being deleted. Separate blob files containing IndexedDB data can end up being deleted because they show up as opaque files to users when they are using disk space recovery programs. +Large value read failure errors occur when an IndexedDB stores large blob values (for example, audio files for an offline podcast app), and then subsequently fails to read those values. This category of errors can occur due to transient causes such as low memory and unrecoverable causes such as source blob files being deleted. -Possible corrective actions for such unrecoverable cases might include notifying the user, deleting the entry from the DB, then attempting to re-fetch the data from the server. - -Errors in this caregory are as follows. More recent browser versions have changed the error types thrown and improved the error messages to help developers distinguish between transient and unrecoverable cases. - -- `NotFoundError` or `NotReadableError` - - : Thrown for unrecoverable errors. -- `DataError` or `UnknownError` - - : Thrown for transient errors, including general disk IO errors. +Different IndexedDB implementations store large values in different ways. For example, in Chrome, large IndexedDB values are not stored directly in the underlying database; instead, they are stored as separate files that are accessed via a reference stored in the database. It has been observed that these separate files can end up being deleted because they show up as opaque files to users when they are using disk space recovery programs. -### Related errors +Possible corrective actions for such cases might include notifying the user, deleting the entry from the database, then attempting to re-fetch the data from the server. -In addition to the error codes sent to the {{ domxref("IDBRequest") }} object, -asynchronous operations can also raise exceptions. The list describes problems that -could occur when the request is being executed, but you might also encounter other -problems when the request is being made. For example, if the result is accessed -while the request is not completed, the `InvalidStateError` exception is thrown. +More recent browser versions have changed the error types and improved the error messages to help developers distinguish between transient and unrecoverable cases. ## Examples @@ -108,7 +84,8 @@ objectStoreTitleRequest.onsuccess = () => { objectStoreTitleRequest.onerror = () => { // If an error occurs with the request, log what it is console.log( - `There has been an error with retrieving your data: ${objectStoreTitleRequest.error}`, + `There has been an error with retrieving your data: + ${objectStoreTitleRequest.error.name}: ${objectStoreTitleRequest.error.message}`, ); }; ``` From 644c88c0dcddd43f38a24aa373585688834a4b64 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Tue, 10 Dec 2024 10:36:14 +0000 Subject: [PATCH 3/5] fixes for code review comments, plus some formatting nits --- .../en-us/web/api/idbcursor/advance/index.md | 2 +- .../en-us/web/api/idbcursor/continue/index.md | 2 +- .../api/idbcursor/continueprimarykey/index.md | 2 +- .../en-us/web/api/idbcursor/request/index.md | 5 --- .../idbdatabase/createobjectstore/index.md | 6 ++-- files/en-us/web/api/idbrequest/error/index.md | 35 ++++++++++++------- .../en-us/web/api/idbrequest/result/index.md | 10 ++++-- 7 files changed, 35 insertions(+), 27 deletions(-) diff --git a/files/en-us/web/api/idbcursor/advance/index.md b/files/en-us/web/api/idbcursor/advance/index.md index 5c53736f46a2895..4a365938a793d86 100644 --- a/files/en-us/web/api/idbcursor/advance/index.md +++ b/files/en-us/web/api/idbcursor/advance/index.md @@ -32,7 +32,7 @@ None ({{jsxref("undefined")}}). This method may raise a {{domxref("DOMException")}} of one of the following types: - `TransactionInactiveError` {{domxref("DOMException")}} - - : Thrown if this IDBCursor's transaction is inactive. + - : Thrown if this `IDBCursor`'s transaction is inactive. - {{jsxref("TypeError")}} - : Thrown if the value passed into the `count` parameter was zero or a negative number. - `InvalidStateError` {{domxref("DOMException")}} diff --git a/files/en-us/web/api/idbcursor/continue/index.md b/files/en-us/web/api/idbcursor/continue/index.md index e52652bda06a976..fc7815918d01191 100644 --- a/files/en-us/web/api/idbcursor/continue/index.md +++ b/files/en-us/web/api/idbcursor/continue/index.md @@ -34,7 +34,7 @@ None ({{jsxref("undefined")}}). This method may raise a {{domxref("DOMException")}} of one of the following types: - `TransactionInactiveError` {{domxref("DOMException")}} - - : Thrown if this IDBCursor's transaction is inactive. + - : Thrown if this `IDBCursor`'s transaction is inactive. - `DataError` {{domxref("DOMException")}} - : Thrown if the key parameter has any of the following conditions: - The key is not a valid key. diff --git a/files/en-us/web/api/idbcursor/continueprimarykey/index.md b/files/en-us/web/api/idbcursor/continueprimarykey/index.md index 68f9b0bffecde09..28157f70378e1f7 100644 --- a/files/en-us/web/api/idbcursor/continueprimarykey/index.md +++ b/files/en-us/web/api/idbcursor/continueprimarykey/index.md @@ -46,7 +46,7 @@ None ({{jsxref("undefined")}}). This method may raise a {{domxref("DOMException")}} of one of the following types: - `TransactionInactiveError` {{domxref("DOMException")}} - - : Thrown if this IDBCursor's transaction is inactive. + - : Thrown if this `IDBCursor`'s transaction is inactive. - `DataError` {{domxref("DOMException")}} - : Thrown if the key parameter has any of the following conditions: - The key is not a valid key. diff --git a/files/en-us/web/api/idbcursor/request/index.md b/files/en-us/web/api/idbcursor/request/index.md index 7a42cdce60f1bfd..9527caeec4a36b8 100644 --- a/files/en-us/web/api/idbcursor/request/index.md +++ b/files/en-us/web/api/idbcursor/request/index.md @@ -14,11 +14,6 @@ The **`request`** read-only property of the {{domxref("IDBCursor")}} interface r An {{domxref("IDBRequest")}} object instance. -### Exceptions - -- `InvalidStateError` {{domxref("DOMException")}} - - : Thrown if the cursor is already advancing. - ## Examples When you open a cursor, the `request` property is then available on that cursor object, to tell you what request object the cursor originated from. For example: diff --git a/files/en-us/web/api/idbdatabase/createobjectstore/index.md b/files/en-us/web/api/idbdatabase/createobjectstore/index.md index 2ad15379f933880..a224a94dccf9c55 100644 --- a/files/en-us/web/api/idbdatabase/createobjectstore/index.md +++ b/files/en-us/web/api/idbdatabase/createobjectstore/index.md @@ -59,7 +59,7 @@ one of the following types: already exists in the connected database. - `InvalidAccessError` {{domxref("DOMException")}} - : Thrown if `autoIncrement` is set to true and `keyPath` is - either an empty string or an array containing an empty string. + either an empty string or an array. - `InvalidStateError` {{domxref("DOMException")}} - : Thrown if the method was not called from a `versionchange` transaction callback. @@ -67,9 +67,7 @@ one of the following types: - : Thrown if the `keyPath` option contains an invalid key path. - `TransactionInactiveError` {{domxref("DOMException")}} - : Thrown if a request is made on a source database that does not exist - (for example, when the database has been deleted or removed). In Firefox previous to version 41, - an `InvalidStateError` was raised in this case as well, which - was misleading; this has now been fixed (see [Firefox bug 1176165](https://bugzil.la/1176165)). + (for example, when the database has been deleted or removed), or if the associated upgrade transaction has completed or is processing a request. ## Examples diff --git a/files/en-us/web/api/idbrequest/error/index.md b/files/en-us/web/api/idbrequest/error/index.md index c85de2a0eb23b23..45b8bf33f3820f9 100644 --- a/files/en-us/web/api/idbrequest/error/index.md +++ b/files/en-us/web/api/idbrequest/error/index.md @@ -10,8 +10,7 @@ browser-compat: api.IDBRequest.error The **`error`** read-only property of the {{domxref("IDBRequest")}} interface returns the error in the event of an unsuccessful -request. If the request is not completed, the error is not available and an `InvalidStateError` exception is -thrown. +request. ## Value @@ -22,26 +21,38 @@ These errors are asynchronous, meaning that they can't be handled via [`try...ca - `AbortError` - : If you abort the transaction, then all requests still in progress receive this error. - `ConstraintError` - - : Received if you insert data that doesn't conform to a constraint when creating stores and indexes. - For example, you will get this error if you try to add a new key that already exists in the record. -- `DataError` or `UnknownError` - - : Received for transient read failure errors, including general disk IO errors. See "Large value read failure errors" below for more details. -- `NotFoundError` or `NotReadableError` - - : Received for unrecoverable read failure errors. See "Large value read failure errors" below for more details. + - : Received if you insert data that doesn't conform to a constraint when populating stores. + For example, you will get this error if you try to add a new key that already exists in the store. +- `NotReadableError` + - : Received for unrecoverable read failure errors. Specifically, this error signals that the record is present in the database, but the value could not be retrieved. See [Transient and unrecoverable read errors](#transient_and_unrecoverable_read_errors) below for more details. - `QuotaExceededError` - : Received if the application runs out of disk quota. In some cases, browsers prompt the user for more space, and the error is received if they decline the request. In other cases, the browser uses heuristics to determine whether more space can be assigned. +- `UnknownError` + - : Received for transient read failure errors, including general disk IO errors. See [Transient and unrecoverable read errors](#transient_and_unrecoverable_read_errors) below for more details. - `VersionError` - : If you try to open a database with a version lower than the one it already has, this error is received. -### Large value read failure errors +### Transient and unrecoverable read errors -Large value read failure errors occur when an IndexedDB stores large blob values (for example, audio files for an offline podcast app), and then subsequently fails to read those values. This category of errors can occur due to transient causes such as low memory and unrecoverable causes such as source blob files being deleted. +Read errors occur when an IndexedDB stores large blob values (for example, audio files for an offline podcast app), and then subsequently fails to read those values even though the associated records are still in the database. -Different IndexedDB implementations store large values in different ways. For example, in Chrome, large IndexedDB values are not stored directly in the underlying database; instead, they are stored as separate files that are accessed via a reference stored in the database. It has been observed that these separate files can end up being deleted because they show up as opaque files to users when they are using disk space recovery programs. +This category of errors can occur due to: + +- Transient causes such as low memory, represented in the spec by the `UnknownError` type. +- Unrecoverable causes such as source blob files being deleted, represented in the spec by the `NotReadableError` type. + +> [!NOTE] +> The errors that represent these cases may vary across browsers. Check the [browser compatibility information](#browser_compatibility) for more details. + +Such errors can manifest in different ways depending on browser, operating system, etc. For example, different IndexedDB implementations store large values in different ways. In Chrome, large IndexedDB values are not stored directly in the underlying database; instead, they are stored as separate files that are accessed via a reference stored in the database. It has been observed that these separate files can end up being deleted because they show up as opaque files to users when they are using disk space recovery programs, resulting in unrecoverable read errors when the IndexedDB is next accessed. Possible corrective actions for such cases might include notifying the user, deleting the entry from the database, then attempting to re-fetch the data from the server. -More recent browser versions have changed the error types and improved the error messages to help developers distinguish between transient and unrecoverable cases. +### Exceptions + +- `InvalidStateError` {{domxref("DOMException")}} + - : Thrown when attempting to access the property if the request + is not completed, and therefore the error is not available. ## Examples diff --git a/files/en-us/web/api/idbrequest/result/index.md b/files/en-us/web/api/idbrequest/result/index.md index 5e21aee2c4e87fc..b35e839940de838 100644 --- a/files/en-us/web/api/idbrequest/result/index.md +++ b/files/en-us/web/api/idbrequest/result/index.md @@ -9,14 +9,18 @@ browser-compat: api.IDBRequest.result {{ APIRef("IndexedDB") }} {{AvailableInWorkers}} The **`result`** read-only property of the -{{domxref("IDBRequest")}} interface returns the result of the request. If the request -is not completed, the result is not available and an `InvalidStateError` exception is -thrown. +{{domxref("IDBRequest")}} interface returns the result of the request. ## Value any +### Exceptions + +- `InvalidStateError` {{domxref("DOMException")}} + - : Thrown when attempting to access the property if the request + is not completed, and therefore the result is not available. + ## Examples The following example requests a given record title, `onsuccess` gets the From 91f299c8d7ea55e8ae80731d238793c4e5c26881 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Wed, 11 Dec 2024 09:22:34 +0000 Subject: [PATCH 4/5] Make phrasing consistent --- files/en-us/web/api/idbrequest/error/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/api/idbrequest/error/index.md b/files/en-us/web/api/idbrequest/error/index.md index 45b8bf33f3820f9..ade8ec5a01528cf 100644 --- a/files/en-us/web/api/idbrequest/error/index.md +++ b/files/en-us/web/api/idbrequest/error/index.md @@ -30,7 +30,7 @@ These errors are asynchronous, meaning that they can't be handled via [`try...ca - `UnknownError` - : Received for transient read failure errors, including general disk IO errors. See [Transient and unrecoverable read errors](#transient_and_unrecoverable_read_errors) below for more details. - `VersionError` - - : If you try to open a database with a version lower than the one it already has, this error is received. + - : Received if you try to open a database with a version lower than the one it already has. ### Transient and unrecoverable read errors From 2775fcfcbb26b81cd9a75ce2bda69302fc990f05 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Thu, 12 Dec 2024 11:16:32 +0000 Subject: [PATCH 5/5] Latest updates based on wbamberg review --- files/en-us/web/api/idbrequest/error/index.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/files/en-us/web/api/idbrequest/error/index.md b/files/en-us/web/api/idbrequest/error/index.md index ade8ec5a01528cf..3b374d5eb97bdc8 100644 --- a/files/en-us/web/api/idbrequest/error/index.md +++ b/files/en-us/web/api/idbrequest/error/index.md @@ -34,19 +34,17 @@ These errors are asynchronous, meaning that they can't be handled via [`try...ca ### Transient and unrecoverable read errors -Read errors occur when an IndexedDB stores large blob values (for example, audio files for an offline podcast app), and then subsequently fails to read those values even though the associated records are still in the database. +Read errors occur when an IndexedDB stores values and then subsequently fails to read those values even though the associated records are still in the database. -This category of errors can occur due to: +Read errors can be one of two types — **transient** or **unrecoverable**: -- Transient causes such as low memory, represented in the spec by the `UnknownError` type. -- Unrecoverable causes such as source blob files being deleted, represented in the spec by the `NotReadableError` type. +Transient read errors are signalled by an `UnknownError` type, and are usually caused by low memory. This shouldn't be a problem for small databases. To avoid low memory situations in large databases, try to split up database access to only load the records you need at any one time, for example using specific [key ranges](/en-US/docs/Web/API/IDBKeyRange) relating to a user's search query or a pagination mechanism. If a low memory error is hit, the user may be asked to close other applications to free up space at the OS-level. -> [!NOTE] -> The errors that represent these cases may vary across browsers. Check the [browser compatibility information](#browser_compatibility) for more details. +Unrecoverable read errors are signalled by a `NotReadableError` type, and are caused by source files being deleted. -Such errors can manifest in different ways depending on browser, operating system, etc. For example, different IndexedDB implementations store large values in different ways. In Chrome, large IndexedDB values are not stored directly in the underlying database; instead, they are stored as separate files that are accessed via a reference stored in the database. It has been observed that these separate files can end up being deleted because they show up as opaque files to users when they are using disk space recovery programs, resulting in unrecoverable read errors when the IndexedDB is next accessed. +For example, some browsers store large values (for example, audio file blobs for an offline podcast app) as separate files that are accessed via a reference stored in the database. It has been observed that these separate files can end up being deleted because they show up as opaque files to users when they are using disk space recovery programs, resulting in unrecoverable read errors when the IndexedDB is next accessed. -Possible corrective actions for such cases might include notifying the user, deleting the entry from the database, then attempting to re-fetch the data from the server. +Possible corrective actions for unrecoverable read errors might include notifying the user, deleting the entry from the database, then attempting to re-fetch the data from the server. ### Exceptions