Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท fmt Package

Go fmt.Errorf() function

Reference for Go fmt.Errorf(): build error values from format strings, wrap errors with %w, wrap several at once, and inspect them with errors.Is and As.

fmt.Errorf creates an error whose message is produced by formatting, just like Sprintf. Its special feature is the %w verb: when the format contains %w with an error argument, the new error wraps that error, and errors.Is, errors.As and errors.Unwrap can still find the original cause.

Wrapping lets each layer add context ("load config: open file: permission denied") without hiding the underlying error that callers may want to test.

Go
return fmt.Errorf("load config %q: %w", path, err)

Try it

Go Adding context with %w

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Go %v hides the cause, several %w, and errors.As

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Syntax

Go
func Errorf(format string, a ...any) error
Name Description
format Format string; may contain %w.
a Operands. Each %w operand must be a non-nil value implementing error.

Returns an error.

  • With no %w, the result is a plain error and errors.Unwrap returns nil.
  • With exactly one %w, the error has an Unwrap() error method returning the operand.
  • With several %w (Go 1.20+), the error has Unwrap() []error, and errors.Is and errors.As check all of them.

Edge cases

  • A %w operand that is not an error produces %!w(string=...) text, and go vet reports it.
  • A nil operand with %w prints %!w(<nil>).
  • %w is only valid in Errorf. Other print functions format it as a bad verb.

Usage notes

  • Wrap when callers may need to inspect the cause; use %v when the cause is an implementation detail you do not want to make part of your API.
  • Message convention: lowercase, no trailing punctuation, no repetition of the wrapped message, e.g. "open config: %w".
  • Prefer %w at the end of the message so the chain reads from outside in: a: b: c.
  • For a plain constant message with no formatting, errors.New is simpler. Since Go 1.24 go vet also warns about non-constant format strings with no arguments: write fmt.Errorf("%s", msg).
  • Use errors.Join to combine independent errors without a message; use Errorf with several %w when you also need a message.
  • Wrapping adds one allocation per layer; it is cheap compared to the clarity it buys. Do not wrap on the hot path of expected failures such as io.EOF checks.
  • Sentinel errors such as ErrNotFound should be compared with errors.Is, never with == after wrapping.