Error conditions, retry, and Error.cause

[jasnell]

Within Workers we have been having a discussion about how to communicate to users via Errors that the conditions leading to an error are temporary and that the user should retry their operation. The how and when to retry is not important here.

For example, a fetch() promise can fail for many reasons. The network path could temporarily be down, the URL could be blocked, the header could be malformated, etc. We want to be able to clearly indicate that the user can/should retry their operation without requiring that the user resort to parsing the error message.

We have several possible paths forward, all of which have the same fundamental problem. We'd like to get consensus on which approach folks would find the most agreeable.

Option 1: New error types

const err = new Error('an error occurred');
Object.defineProperty(err, 'name', { value: 'RetriableError' });

Option 2: Non-standard own properties on Error

const err = new Error('an error occurred');
err.retriable = true;

Option 3: Using cause

const err = new Error('an error occured', { cause: { retriable: true } })

Option 4: Using AggregateError

// The first object is always an error but the additional things communicate
// the additional structured information we want.
const err = new AggregateError([
  new Error('an error occurred'),
  { retriable: true }
])

Option 5: ??

Other ideas?

Current Thinking

My current thinking here is to prefer Option 3, using the cause property.

Specifically, pulling out to a logical level: The purpose of the cause is to communicate the reason for this error. That reason might be that another Error was thrown, or it might be that some other condition occurred. For instance, the network was down, or there was an internal error, etc. So let's differentiate between Error and Condition.

If I have a transient condition and want to communicate that the user should retry their operation, then I could logically do something like:

cont condition = {
  // The condition is temporary....
  transient: true,
  // The operation is retriable...
  retriable: true,
};
const err = new Error('oops that failed', { cause: condition });

The challenge with this, of course, is interoperability. If workers chooses to use cause in this way but other fetch() implementations choose to use cause in other ways then we can run into interop issues. To be clear, ALL of the options suffer from this exact problem.

Proposal

The proposal I would like to make is to define a new ErrorCondition interface specifically for use with cause

Essentially (treat this as a discussion example to express intent... the actual proposal can be refined):

dictionary ErrorConditionInit {
  boolean transient = false;
  boolean retriable = false;
  DOMString name = "";
};

interface ErrorCondition {
  constructor(optional DOMString message = "", optional ConditionInit init = {});
  readonly attribute boolean transient;
  readonly attribute boolean retriable;
  readonly attribute DOMString name;
  readonly attribute DOMString message;
}

Note that this interface intentionally mimics DOMException with the inclusion of a name and message accessors.

Example use (assuming the proposal to add cause to DOMException goes through):

const err = new DOMException('The operation failed', {
  name: 'NETWORK_ERR',
  cause: new ErrorCondition('The network path is down', {
    transient: true,
    retriable: true,
  })
});

console.log(err.cause.transient);  // true
console.log(err.cause.retriable); // true

To be clear, I don't really have strong opinions on exactly how we solve this use case. My only requirement is that we have a mechanism for reliably communicating transient/retriable conditions that is interoperable across runtimes.

Some questions

1. How are retriable errors like this handled elsewhere on the web?

[jasnell]

cc @domenic @annevk ... We'd love your input on this topic as well.

[jasnell]

Also... @kentonv @mcollina

[benjamingr]

An error subclass seems like the natural/standard way to communicate a finer grained error, then that can have a retriable property or whatnot.

I always thought of .cause as the error that caused that error to help investigate errors deeply (e.g. if your service that depends on an API failed, it might be useful to know that API returned a 503 status when debugging even if it's an error related to your business model)

[jasnell]

as the error that caused that error

But what if it's not an Error that caused the error? Remember, JavaScript allows you to throw anything, and some Errors are not caused by other errors as much as they are caused by conditions that are not met (the network being down is not an error on it's own, it's just a temporary state).

[ljharb]

Note that this (examples of a non-error object) includes any Promise rejections, like reject() in a Promise executor, Promise.reject() anywhere, or any throw object.typo variant that might appear.

[domenic]

Yeah, my understanding was cause was mainly aimed at stack stitching of multiple Error instances. It's not a generic way to smuggle in more data into a single field; creating actual fields on a subclass or expando seems better for that.

[ljharb]

That's not the motivation as I understand it; that's what AggregateError is more aimed at.

[jasnell]

Ok, so the option 5 here is something like:

class RetriableError extends Error {
  constructor(message) {
    super(message);
    Object.defineProperty(this, 'name', { value: 'RetriableError' });
  }
}

[jasnell]

@domenic ... if we go the route of a new Error subclass, I'd like to make sure we can do it in a way that ensures we won't clash down the road with any web platform stuff. To that end, do you think there'd be any interest among browser implementors for either a new error type or standardized property on DOMException to indicate retriability?

[domenic]

I'm not sure. My initial impression is that it seems rather difficult because it's ambitious. If I were to go through the hundreds of thrown exceptions on the web platform, I'd be surprised if they neatly fell into "retriable" and "non-retriable" buckets. E.g. for fetch() we purposefully avoid giving much programmatic access to information about network errors, for security reasons. (But maybe a single retriability bit would not be a security leak?)

The places that seem most promising are I/O specs like fetch(), IndexedDB, and fs.spec.whatwg.org. Maybe file issues on those repos and see if this is a problem web developers have, and if they'd benefit from such a bit? And then security discussions could be had there too.

[jasnell]

I'll get an issue opened in the webidl repo to start the conversation.

[legendecas]

To my understanding, I'd find this feature would be better served with option 1 or option 2, as the additional information is describing the error instance itself, rather than their "correlated" error instances. For option 2, "Non-standard own properties" may be standardized. If this "retriable" bit doesn't impose security concerns, I'd believe it could be a benefit to other web APIs too.

Yeah, my understanding was cause was mainly aimed at stack stitching of multiple Error instances.

That's not the motivation as I understand it; that's what AggregateError is more aimed at.

IMO cause was intended for augmenting errors with correlated contextual information. It is not like AggregateError aggregating arbitrary errors, which can be totally unrelated.

That being said, I think option 1 (or subclasses) and option 2 are valuable to be explored.

[mcollina]

I think using cause would cause compatibility problems with whoever is expecting an error to be there. I would

In case of an added property, I recommend using a global symbol name as a property, as everybody has been stitching properties on errors for years. I think you'd want to avoid naming collisions. Something like err[Symbol.for('errors.meta)] = { retriable: true }.

This would be a generalization beyond fetch.

[benjamingr]

But what if it's not an Error that caused the error?

Then I would not expect .cause to be set but instead additional/different properties to be set on the error subclass. This is similar to the DOMException subclass having a .code (or Node errors, similarly). The way to add properties to errors is very common (e.g. in the context of HTTP requests, axios - its Errors expose a reference to the response).

Remember, JavaScript allows you to throw anything, and some Errors are not caused by other errors as much as they are caused by conditions that are not met (the network being down is not an error on it's own, it's just a temporary state).

Sure and while I don't personally like non Errors thrown because they make debugging harder - I would absolutely expect the .cause of an error that resulted from another error to contain that other error even if that error itself isn't an Error (e.g. if it's a string).

---

I would also be interested in hearing more about your use case or where the platform can decide for the application whether something is retriable or not.

I guess the closest we have is EAGAIN as a code in some cases.

[jasnell]

I would also be interested in hearing more about your use case or where the platform can decide for the application whether something is retriable or not..... I guess the closest we have is EAGAIN as a code in some cases.

EAGAIN is a good example. A number of 4xx http status codes are also examples.

Ok, from the discussion here, it's looking like the preferred choices are either (a) create a new Error type or (b) define a new property on the Error. Out of those two choices, do folks have a preference?