What’s the difference between these three functions from Go’s standard packages:
Wrapf returns an error annotating err with a stack trace at the point Wrapf is called, and the format specifier. If err is nil, Wrapf returns nil.
errors.Errorf(), provided an error via
Errorf formats according to a format specifier and returns the string as a value that satisfies error. Errorf also records the stack trace at the point it was called.
fmt.Errorf(), provided an error via
Errorf formats according to a format specifier and returns the string as a value that satisfies error.
If the format specifier includes a %w verb with an error operand, the returned error will implement an Unwrap method returning the operand. It is invalid to include more than one %w verb or to supply it with an operand that does not implement the error interface. The %w verb is otherwise a synonym for %v.
When one should be used instead of others?
First, a correction:
github.com/pkg/errors is very popular, and is maintained by some prominent Gophers. It is, however, largely (though not completely*) obsoleted by Go 1.13’s extended error support.
Understanding the difference between those three functions requires a bit of a history lesson.
Prior to Go 1.13, there was no officially-recognized way to "wrap" errors.
github.com/pkg/errors filled this gap with the
Wrapf methods. This allowed wrapping an error with additional context (including a stack trace), while retaining the original error in pristine form.
When Go 1.13 was in development,
github.com/pkg/errors was used to influence the new API, but the final version differed slightly. Rather than
Wrapf methods, they decided to extend the
fmt.Errorf method with a new
%w verb, which would perform error wrapping for you.
This means that the following bits of code are roughly* equivalent:
import "github.com/pkg/errors" /* snip */ return errors.Wrapf(err, "bad things")
// +build go1.13 import "fmt" /* snip */ return fmt.Errorf("bad things: %w", err)
When Go 1.13 came out, and the
%w verb was added to
github.com/pkg/errors followed suit and added the same support, so now
Wrapf is effectively obsolete.
So this brings us to the present day recommendations:
- If you want stack traces in your errors, use
github.com/pkg/errors.Errorfto wrap errors.
- If you don’t care about stack traces, use
fmt.Errorffrom the standard library.
- Never use
errors.Wrapfany more. It’s for backward compatibility.
*The standard library’s
error package still does not include stack traces, so
github.com/pkg/errors is still popular for that.
Answered By – Flimzy
Answer Checked By – David Marino (GoLangFix Volunteer)