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.
var p *MyError // nil pointer var err error = p // interface holds (type *MyError, value nil) fmt.Println(err == nil) // false
Try it
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.
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. Declarevar err errorinstead ofvar e *MyErrorwhen the variable is later returned, or use an explicitreturn nilon 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. Usevar target *MyError; errors.As(err, &target); never compareerrto(*MyError)(nil). - Interface method sets matter. The buggy shape appears with any interface:
io.Reader,http.Handler, your own. It is not specific toerror. - Debug with
%Tand%#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
staticcheckand thenilnessanalyzer catch some of these comparisons, but not all, so a test of the success path is still the best protection.
Related
- interface, any, Method sets, Zero values, errors.As
- Lessons: Interface Internals, Custom Errors, Interfaces