How does walking up the tree work in errors.Is() and errors.As()? Is it depth-first, i.e. Unwrap() to []error and then fully walk each resulting tree, or is it breadth-first, i.e. Unwrap() to []error and then do each of those before unwrapping them and doing the next set. I assume that it's depth-first, as that's simpler, but breadth-first could also make sense. It would also be possible to convert from a default of breadth-first to a depth-first by implementing custom unwrapping logic, but going the other way could be difficult.

How does walking up the tree work in errors.Is() and errors.As()?

Depth-first. Unwrap to an []error and walk each error in the list in turn. This is what every existing multierr implementation I looked at does.

This would also subsume #50819 and I imagine any other similar proposals.

Maybe it should wait for a generic iteration standard, but should there be some errors.Each function that goes through each link in the chain? My suspicion is there’s not much to do besides As-ing and Is-ing, but it does seem like an absence, since there will be some internal function that works like that, which could potentially be exported.

Is and As are separate implementations for efficiency reasons, so there's no internal Each function. This proposal does make the case for an exported Each or similar stronger, since iteration becomes more complicated.

We should probably wait and see what happens with generic iteration, however.

Does Unwrap return a reference to the internal slice in the error?
If so, that would make the internal slice reference externally mutable, which seems unfortunate (but not a dealbreaker).

If not, and it returns a copy, then it would allocate, which also seems unfortunate (but probably not a dealbreaker).

Does Unwrap return a reference to the internal slice in the error?

Unspecified, but the contract for it says that the caller must not modify the slice, so it may.

Perhaps Split should copy the result into a new slice. This would leave Is and As potentially allocation-free, while adding a layer of safety (and an allocation) to the relatively unusual case of manually inspecting the individual errors.

This strikes me as a significant step forward in figuring out the multi-error question. Thank you!

The only part of this that doesn't seem entirely spot-on is errors.Split.

What is the use case for errors.Split?

Figuring errors.Split would be used like errors.Unwrap, I grepped through the code sitting around on my laptop and found only a single use of errors.Unwrap. It was used to check recursively whether any error in the chain satisfied a predicate. It would be interesting to analyze other uses in a larger corpus.

Walking an arbitrary error tree using errors.Split and errors.Unwrap will be annoying. I wonder whether a callback-based errors.Walk that walks the entire error tree would be a better API. There are a lot of details to specify for such an API, but with a bit of care, it could be more powerful and flexible than errors.Split. It could be used to implement errors.Is and errors.As. And it sidesteps questions about ownership and modification of returned error slices.

(The details about errors.Walk include things like: Does it call back for all errors, or only leaf errors? Does it use a single callback like io/fs.WalkDir or separate pre- and post- callbacks like golang.org/x/tools/ast/astutil.Apply? Does it support early stopping?)

On the topic of slice copies, a minor question. Does errors.Join make a copy of the variadic arg? I'd argue for yes, and ameliorate the pain a bit by adding a small default backing store to the struct. Aliasing bugs are miserable.

I find that the main reason I unwrap my own multierrors is so that I can report them separately to my logging service or display them as a list in a CLI. The original xerrors formatting proposal was dropped for being too complicated but I think that an easy to use error walking mechanism might make it easy to let users figure out how they want to display and format all the suberrors on their own.

This proposal has been added to the active column of the proposals project
and will now be reviewed at the weekly proposal review meetings.
— rsc for the proposal review group

If I hadn't read the comments, I might have thought that after the "Join" error, I could use "Split" to parse it out.

"errors.Split" does the same thing as "errors.Unwrap", but deals with multiple errors. So instead of "Split" which is the opposite of "Join", it should be "UnwrapMultiple" or "Walk" which is more appropriate.

The errors.Unwrap function is unaffected: It returns nil when called on an error with an Unwrap() []error

Since there is no reaction to multiple error conditions, the naming should also be differentiated, such as ”UnwrapMultiple() []error “.

What is the use case for errors.Split?

We need to provide some reasonably convenient way to get at the underlying errors of a multierr. Perhaps Split isn't the right API here (although I still feel pretty good about it), but we need something.

I wonder whether a callback-based errors.Walk that walks the entire error tree would be a better API.

Perhaps there's a case for such an API, but I think it's distinct from this proposal. Accessing the component errors of a multierr is different from a full tree walk.

Does errors.Join make a copy of the variadic arg?

Yes.

I'm 100% on

• defining Unwrap() []error
• changing Is/As to support the new Unwrap
• updating fmt.Errorf to allow multiple %w

If those were the only things accepted I'd be happy and it would be more than enough to allow external multierrors to interoperate with each other and std.

I do think there 100% does need to be a tree walking API—but it's too early to decide what that looks like. Once the protocol above is enshrined in errors, it's simple enough to experiment with that outside std.

I'm not 100% sold on the name for Split but there should probably be such a func in std, regardless of name, to pair with Unwrap. I don't think it would be much of an impediment if this weren't included, however.

I'm not really sold on Join. I see the utility of including a basic multierror in std, but just gluing the errors together with a sep seems like it could get messy when multierrors get composed. I think, like a tree walking API, it should be left out and experimentation allowed to continue outside std for now.

We need to provide some reasonably convenient way to get at the underlying errors of a multierr.

I'm not so sure that we do.

For uses (testing?) in which you really specifically want to unwrap from an error that has an Unwrap() [] method, you can use a type assertion. (errors.Unwrap is less than 10 LOC, and consists entirely of a type assertion.)

But I suspect that almost nobody wants specifically to unwrap a multi-error exactly one layer deep. Rather they want to ask the general question "what errors are in this tree?". So I think that's the right form of API to add. And I think it'll get created internally anyway to implement Is and As.

Maybe this proposal should simply omit Split?

Rather they want to ask the general question "what errors are in this tree?".

The fact that errors.Unwrap is so seldom used indicates to me that people don't want to ask this question. They use Is and As to ask "is this error in the tree?" or "is there an error of this type in the tree?" instead.

I'm not certain how much of a use case there is for a tree walk that doesn't preserve the structure of the tree. It would be nice to see real-world examples of this in practice.

I grepping in my own dependencies and grabbed all the uses. I ignored the standard library, static analyzers, linters, and then pulled all the uses that were not in tests. Here they are:

x/tools uses errors.Unwrap to get to the innermost error, without regard for the structure of what is above it. I suspect that this could would be better served by being able to evaluate a predicate on every error in the tree.

aws-sdk-go uses errors.Unwrap to recursively evaluate a predicate on every error in the tree, with early stopping.

containerd uses errors.Unwrap in a way that I find confusing and might be buggy. It uses it to peel back exactly one layer of wrapping and then compares this to a particular error using string matching. This is fragile (if another wrapping layer gets introduced) and would probably be better served by a way to check every error in the tree.

containerd uses errors.Unwrap again to peel back exactly one layer of wrapping. It looks like errors.As would be a better fit here; I don't see any reason why exactly one layer is the right answer here.

jwt uses errors.Unwrap to implement Is. In this case, errors.Unwrap is unnecessary, because e is known to have a concrete type that implements Unwrap; the code could call e.Unwrap directly instead.

I then grabbed two uses in tests at random:

errwrap uses errors.Unwrap specifically to test that it is compatible with how the standard library defines errors.Unwrap. It has no actual use for errors.Unwrap or opinion about its behavior.

pgconn uses errors.Unwrap to test its own error's compability with package errors. It looks like it would be equally well served by errors.As.

So far, I see no evidence that anyone cares much about the structure of the error tree. It looks to me like they are all: misusing the API (evidence that the API is wrong); using the wrong API (evidence that the API is wrong); using the API pointlessly; or using the API to evaluate a predicate "anywhere along the error chain".

That's useful data; thanks.

We don't have error trees right now; we have an error chain. We can't tell whether people will care about the structure of trees by looking at how they work with linear chains.

It'd be interesting to look at use of existing multierr packages to see how often multierrs are converted back to lists of errors.

It'd be interesting to look at use of existing multierr packages to see how often multierrs are converted back to lists of errors.

I agree. Can I leave that for you to do? I've exceeded my time allotment for this for a while. :)

I'm 100% on

• defining Unwrap() []error
• changing Is/As to support the new Unwrap
• updating fmt.Errorf to allow multiple %w

If those were the only things accepted I'd be happy and it would be more than enough to allow external multierrors to interoperate with each other and std.

I do think there 100% does need to be a tree walking API—but it's too early to decide what that looks like. Once the protocol above is enshrined in errors, it's simple enough to experiment with that outside std.

I agree with you very much, we should focus on the original core API supporting the multiple error model first, and then expose the complexity to the user. Before that, we can experiment with Join, Split, Walk, etc.

Most importantly, decide the definition of Unwrap() []error.

I agree. Can I leave that for you to do? I've exceeded my time allotment for this for a while. :)

I'm going to go look, but probably not until next week. Had a few days of meetings, and I'm now exhausted and behind on everything. :)

Given the size of these error trees, where even "a dozen" would be huge, I would suggest the solution to iteration is simply to define that the traversal used by the rest of the library will be used to return a []error populated in the traversal order used by the rest of the code, or a simple tree struct. Such a small set of values doesn't rate having the iteration proposal placed as a blocker in front of it.

It's rarely used functionality (as observed above for Unwrap in general), on the error path (not the happy path where performance is generally a bigger deal), for a rarely-used use case where Is and As is not enough. Code that is generating millions or billions of complex error trees per second that it then somehow needs to deal with in a complicated manner is too broken to be saved by even zero-performance error tree iteration.

I'd like to help encourage my team to use errors.Is (or evens errors.As) for testing instead of using text-based comparisons. While researching to provide best practices I created the following code for use in the Golang Playground:

https://gist.github.com/BenjamenMeyer/ef9926913dcc3b165da8f25a459442a9

I was quite surprised that errors.Unwrap would only extract the first layer (may be I'm doing something wrong?) but then came across this proposal. Honestly, IMHO most are looking to be able to use the errors.is and errors.As APIs to test a full error chain reliably instead of having to decode a string, which could be unreliable.

Love the proposal here but would certainly be happy with something that would allow errors.Is to detect any given error is part of the provided error when built up from several in a row - e.g returning an error up from a lower level in the code to a higher level several times and being able to see the lower error is there.

NOTE: The code in the gist is just a sample for this explicit behavior. Consider the list of errors representing the layers of the code with the singular error what the code actually sees in the tests; yet it fails to be able to detect the lower level errors.

HTH

Follow-up: This seems to be something that has gone back to 1.13-betas with properly wrapping and detecting the various layered errors: https://groups.google.com/g/golang-nuts/c/SwKZ-qJmZl0?pli=1

I've compiled some data on use of splitting multierrors created with go.uber.org/multierr back inmto the original list of errors.

I started with a list of 1976 modules known to pkg.go.dev which import go.uber.org/multierr. I populated my local module cache with this set by running go get $MOD@latest for each one. I then used grep to build a list of .go files in my module cache that imported this package, and filtered this down to only files in the latest version of each module when there were duplicates. There's probably a more elegant way to do this, but it worked for me.

This gave me 5981 unique files that import go.uber.org/multierr.

Of those, 182 call multierr.Error to convert an error into a []error.

The following is a set of links to uses of multierr.Error calls, with a few deleted packages removed. Many of these look to be forks of the same original code; I haven't made any effort to deduplicate these.

Looks great and can't wait to apply it to engineering!

Referring to bokwoon95 #53435 (comment)

interface{ Unwrap() []error } // <-- errors.Unwrap returns nil, potentially confusing.

and kortschak #53435 (comment)

I was sort of surprised looking at the errors.Join documentation that it is not mentioned that the returned error implements the Unwrap() []error method. In the absence of the errors.Split function, this method has significantly reduced discoverability.

This muliterror feature is incomplete, because I am required to make err.(interface{ Unwrap() []error }) checks myself to call Unwrap() []error explicitly to get and handle multiple errors. Split(error) []error func, that return a slice of errors for both regular single error and multierror cases would help here.

@dimandzhi This issue is closed. I created #65428 as a new issue for follow up. You can propose new ideas there.