Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท Concepts

The nil interface pitfall in Go

Explains why a Go interface holding a nil pointer is not equal to nil, how it breaks error returns, how to detect and avoid it, and how interfaces are represented.

An interface value in Go is a pair: a dynamic type and a dynamic value. The interface is nil only when both are absent. If you put a nil pointer of type *MyError into an error, the type half is *MyError and the value half is nil. The pair is not empty, so err != nil is true even though the pointer inside is nil.

This bites most often when a function returns a concrete pointer type through an interface result, usually error. The code looks right, the pointer is nil, and still callers see an error. The fix is to return the literal nil for the interface, not a typed nil pointer.

Go
var p *MyError         // nil pointer
var err error = p      // interface holds (type *MyError, value nil)
fmt.Println(err == nil) // false

Try it

Go The classic bug and its fix

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 Seeing the pair, and checking safely

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

How an interface value is stored (conceptually):

Interface value Dynamic type Dynamic value == nil
var e error none none true
var e error = (*MyError)(nil) *MyError nil pointer false
var e error = &MyError{} *MyError non-nil pointer false
var a any = 0 int 0 false

Comparison rule. iface == nil is true only when the interface has no dynamic type. To ask "is the thing inside nil?" you need a type assertion (p, ok := err.(*MyError); ok && p == nil) or reflection (reflect.ValueOf(x).IsNil() for the pointer-like kinds).

Errors and edge cases: calling a method through a typed nil interface calls that type's method with a nil receiver. It succeeds if the method handles nil and panics with a nil pointer dereference otherwise. Calling a method on a truly nil interface always panics. reflect.Value.IsNil panics for kinds that cannot be nil (such as int).

Usage notes

  • Return nil, not a nil pointer, from functions with interface results. Declare var err error instead of var e *MyError when the variable is later returned, or use an explicit return nil on the success path.
  • Do not assign a concrete pointer to an interface until you know it is non-nil. Write if p != nil { return p }; return nil.
  • Concrete error types in errors.As. Use var target *MyError; errors.As(err, &target); never compare err to (*MyError)(nil).
  • Interface method sets matter. The buggy shape appears with any interface: io.Reader, http.Handler, your own. It is not specific to error.
  • Debug with %T and %#v. fmt.Printf("%T %#v", err, err) instantly shows *main.MyError (*main.MyError)(nil).
  • Nil-receiver methods are legitimate. Some types (such as trees or linked lists) are written so that methods work on nil receivers. If a type is designed that way, document it.
  • A nil func, map, slice or channel in an interface behaves the same as a nil pointer: the interface is not nil.
  • Linters. Static analyzers such as staticcheck and the nilness analyzer catch some of these comparisons, but not all, so a test of the success path is still the best protection.