The Nil Interface Trap

An order service starts rejecting every order, including orders that are valid. For each valid order, the logs show the same line: save failed: <nil>. The function that checks the order did not find a problem and returned nil, yet the check err != nil in its caller is true.

panic: runtime error: invalid memory address or nil pointer dereference
Copy

The stack trace places the panic inside Error, at the read of e.OrderID. The function was called and began to run, and only the field read failed. A method that checks its receiver first does not panic at all:

func (e *OrderError) Error() string {
	if e == nil {
		return "no order error"
	}
	return fmt.Sprintf("order %d failed", e.OrderID)
}
Copy

A method with a value receiver cannot run on a nil pointer, because the call must first copy the value that the pointer refers to. Through an interface, the generated function from How Interface Values Work reports this with its own text. For a method Label declared on Order, the message is panic: value method main.Order.Label called using nil *Order pointer. If the compiler can prove the dynamic type and call the method directly, the panic is the plain nil pointer message instead. A call through an interface that holds no value at all panics with the nil pointer message, because the first word is nil and there is no method table to read.

The opening program printed <nil> instead of panicking, because fmt handles this case. The function catchPanic in fmt/print.go recovers a panic from an Error or String method, and it prints <nil> if the argument is a nil pointer. That behavior hides the panic, and it makes the log line look like an empty value.

The Repairs

The cause is a function that has a concrete pointer type as its result, and whose result is later converted to an interface. Three repairs exist, and the first two remove the conversion of a nil pointer.

Declare the result as error. This is the usual repair. When validate has the result type error, its return nil produces a nil interface directly, and no pointer is involved.

Output:

<nil>
order 1002: no customer
Copy

Return a literal nil. Sometimes a function must keep a concrete variable inside its body, for example while it builds up the error. Check that variable, and write nil in the return statement when there is nothing to report.

func save(o Order) error {
	var failure *OrderError
	if o.Customer == "" {
		failure = &OrderError{OrderID: o.ID, Reason: "no customer"}
	}
	if failure == nil {
		return nil // not "return failure", which would set the type word
	}
	return failure
}
Copy

Do not store a typed nil. A nil pointer of a concrete type is called a typed nil, and a parameter of interface type has the same problem with it. A call such as export(buffer), where buffer is a nil *bytes.Buffer and the parameter is an io.Writer, passes a non-nil interface. Any nil check inside export then passes, and the failure appears at the first write. The check belongs in the caller, which knows the concrete type.

Do not repair this by comparing with a typed nil inside the caller. The check err == (*OrderError)(nil) does compile and it does return true here. However, it works for one type only, and every caller would have to know which concrete type to test.

Detecting a Typed Nil

When an error prints as <nil> and is still not equal to nil, the verb %T of the fmt package answers the question immediately. It prints the dynamic type of the value. A plain %v prints the same text for both cases, so it cannot tell them apart, while %#v shows both the type and the value.

Output:

empty:           %T=<nil> %v=<nil> %#v=<nil>
holdsNilPointer: %T=*main.OrderError %v=<nil> %#v=(*main.OrderError)(nil)
Copy

A %T result of <nil> means a true nil interface. Any other result means that a typed value is stored. Here, *main.OrderError names the type to search for: some function between the error's source and the failing check returns that pointer type.

Using This in an Interview

An interface value is nil only when both its type word and its data word are nil. A nil pointer stored in an interface sets the type word, so the interface does not equal nil, and this most often appears when a function returns a nil *OrderError as an error. A likely follow-up asks how to prevent it. Declare the result as error and return a literal nil, so no nil pointer is ever converted.

Key Takeaways

• An interface value equals nil only when both its type word and its data word are nil.
• Converting a nil pointer to an interface sets the type word, so the result does not equal nil.
• A method with a pointer receiver can run on a nil pointer, and it panics only when it reads or writes through the receiver.
• fmt recovers that panic and prints <nil>, which hides the cause in logs.
• Functions that return errors should declare the result as error and return a literal nil.
• %T tells the two cases apart, while a plain %v prints <nil> for both.

An interface value that holds a nil pointer is a real value with a known type, even though the pointer inside it is nil. Comparing it with nil asks only whether the interface holds something, and it does. The practical rule is short: when a function reports an error, its result type should be error, and its success path should say return nil.