Add docs for improved error reporting for IndexedDB large value read failures

[chrisdavidmills]

Description

Chrome has updated its error reporting for IndexedDB large value read failures with transient causes such as low memory and unrecoverable causes such as source blob files being deleted.

Chrome 130 updates the DOMException types to be more appropriate, and Chrome 132 further updates them and improves the associated error messages. The data source is https://chromestatus.com/feature/5140210640486400.

In this PR, I have organized the different IDBRequest.error types into categories to hopefully make them easier to parse, and described and explained the large value read failure errors.

Motivation

Additional details

Related issues and pull requests

[github-actions]

Preview URLs (6 pages)

• /en-US/docs/Web/API/IDBCursor/key
• /en-US/docs/Web/API/IDBCursor/primaryKey
• /en-US/docs/Web/API/IDBCursor/request
• /en-US/docs/Web/API/IDBDatabase/createObjectStore
• /en-US/docs/Web/API/IDBObjectStore/clear
• /en-US/docs/Web/API/IDBRequest/error

(comment last updated: 2024-12-03 11:44:00)

[inexorabletash]

The phrasing "error names can be returned in the exception object" read a bit weird to me. How about "The exception object will have one of the following names, depending on what caused the error." ?

[chrisdavidmills]

Yup, that reads much better. I've used your wording, in the next commit.

[inexorabletash]

The asynchronous errors like this are not "thrown" in the sense that you can't try/catch them from script. So I would avoid that phrasing here and below.

From a script perspective, an error event is fired at the IDBRequest; if the developer has assigned an event handler, then the handler can inspect the request's error property and specifically error.name to see what the cause was.

[chrisdavidmills]

Right, OK, that makes sense. I've added a bit of text that comments on how these errors can be handled, based on your text above. Let me know if you think that approach makes sense.

I've also improved the code example snippet on the page so that the event handler logs the error name and message, rather than just the error object.

[chrisdavidmills]

I've also removed the "thrown" language in each case.

[inexorabletash]

Typo: "in" should be "if".

But more importantly, SyntaxError is thrown synchronously when certain methods are called. It would never appear as a request's error. So this is not useful for this page.

[chrisdavidmills]

Duh, yeah, sorry. I should have clocked this. I wrote most of the original IndexedDB MDN docs but have not looked at them for years! TBH, they could really use an overhaul, but that is beyond the scope of this PR.

For now, I've removed the errors that shouldn't be listed here, gone through the spec to see what methods they are thrown on, and ensured they are included in their ref pages' "Exceptions" sections.

[inexorabletash]

TransactionInactiveError is thrown synchronously when certain methods are called. It would never appear as a request's error. So this is not useful for this page.

[chrisdavidmills]

As before, I've removed it from this page and made sure that it is covered on the relevant method/property pages.

[inexorabletash]

ReadOnlyError is thrown synchronously when certain methods are called. It would never appear as a request's error. So this is not useful for this page.

[chrisdavidmills]

As before, I've removed it from this page and made sure that it is covered on the relevant method/property pages.

[inexorabletash]

InvalidStateError is thrown synchronously when certain methods are called. It would never appear as a request's error. So this is not useful for this page.

[chrisdavidmills]

As before, I've removed it from this section and made sure that it is covered on the relevant method/property pages.

In this case, an InvalidStateError is thrown when you try to access the actual error property before the request is complete. So I've mentioned that on this page.

[inexorabletash]

Some browsers prompt the user; others use heuristics. So this could be softened a bit.

[chrisdavidmills]

I've updated it to:

Thrown 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.

Does that work for you?

[inexorabletash]

Per above, not "thrown" but returned via the request's error property.

[chrisdavidmills]

As before, I've removed the "thrown" wording.

[inexorabletash]

Not new, but this doesn't make much sense in this context.

"In addition to the error codes sent to the IDBRequest object..." - so far so good, that's what this page is about

"... asynchronous operations can also ..." - that doesn't make sense. This whole page is about how asynchronous operations that occur when the request is being executed, so this is like saying "In addition to A, there's also A".

Finally "...raise exceptions." - as noted, async operations can't raise exceptions, they fire error events.

[chrisdavidmills]

Yup, totally agree. I think I can just remove this section. This page is about async errors related to requests; there is no need to highlight that other errors occur in other places.

[inexorabletash]

This is all a Chromium implementation detail, so doesn't really belong in MDN like this. Different browsers could (and do) approach storing large values very differently.

This page should lead with the error types (below), explain the cause (maybe mentioning that implementations can store values in different ways) and how developers should reason about what to do (e.g. retry if recovery is possible, wipe the database, etc)

[chrisdavidmills]

Entirely agree. I've rephased/restructured it as suggested, and indicated that the storage description is just an example, which is the way Chrome does it.