Why does json.Unmarshal work with reference but not pointer?

Question

This example from the json.Unmarshal docs (slightly modified for simplicity to use Animal instead of []Animal) works, no errors:

Playground link of working example

// ... var animals Animal err := json.Unmarshal(jsonBlob, &animals) // ... 

But this slightly modified example doesn't:

Playground link of non-working example

// ... var animals *Animal err := json.Unmarshal(jsonBlob, animals) // ... 

It displays this obscure error that really isn't helpful (looks more like a function call than an error IMO):

json: Unmarshal(nil *main.Animal)

This appears to be because animals is an uninitialized pointer. But the docs say (emphasis mine):

Unmarshal unmarshals the JSON into the value pointed at by the pointer. If the pointer is nil, Unmarshal allocates a new value for it to point to.

So why does unmarshaling fail in the second example and show that obscure error?

(Also, is it "unmarshalling" or "unmarshaling" (one L)? The docs use both.)

Answer 1

You've encountered an InvalidUnmarshalError (see lines 109 and 110 in decode.go).

// An InvalidUnmarshalError describes an invalid argument passed to Unmarshal.
// (The argument to Unmarshal must be a non-nil pointer.)

It seems the docs could do with some clarification as the quote above and the comment below from the Unmarshal source seem to contradict each other.

If the pointer is nil, Unmarshal allocates a new value for it to point to.

Answer 2

Because your pointer is nil.

If you initialize it it works: http://play.golang.org/p/zprmV0O1fG

var animals *Animal = &Animal{} 

Also, it can be spelled either way (consistency in a single doc would be nice, though): http://en.wikipedia.org/wiki/Marshalling_(computer_science)