The empty address book
You write a function to fetch a configuration file. It returns a pointer to a struct. Back in your main routine, you reach for the DatabaseURL field. The program stops. The terminal prints panic: runtime error: invalid memory address or nil pointer dereference. You stare at the line that worked perfectly in your head. The code tried to read a field from a pointer that points nowhere.
Go does not invent data. When a pointer is nil, it holds no memory address. Dereferencing it means asking the runtime to follow a blank map. The runtime refuses to guess and halts execution immediately. This panic is the language telling you that a value you expected to exist was never created.
Pointers and the nil floor
A pointer in Go is a variable that stores a memory address. The type *Config means a pointer to a Config struct. When you declare a pointer without assigning it, Go sets it to its zero value. The zero value for every pointer type is nil.
Think of nil like an empty envelope. You can pass the envelope around, check if it is empty, or put a letter inside it. You cannot read the letter until the envelope actually contains one. Go makes this explicit. Other languages might auto-initialize objects or return empty defaults. Go leaves the pointer empty and expects you to handle the absence.
This design keeps memory predictable. The runtime never allocates hidden structs behind your back. If you want a struct, you ask for it with new() or a composite literal. If you forget, the pointer stays nil, and the next access crashes. The crash is a feature. It catches missing initialization before the bug spreads through your system.
Pointers are explicit. Nil checks are cheap. Write them where absence is possible.
Minimal example
package main
import "fmt"
// Config holds application settings.
type Config struct {
DatabaseURL string
Timeout int
}
// LoadConfig simulates reading a file.
// It returns nil when the file is missing.
func LoadConfig(path string) *Config {
// Return nil to signal missing data.
if path == "" {
return nil
}
// Allocate a new struct and return its address.
return &Config{DatabaseURL: "postgres://localhost", Timeout: 30}
}
func main() {
// path is empty, so LoadConfig returns nil.
cfg := LoadConfig("")
// Accessing a field on a nil pointer triggers the panic.
// The runtime cannot find memory to read from.
fmt.Println(cfg.DatabaseURL)
}
Run this and the program halts with panic: runtime error: invalid memory address or nil pointer dereference. The stack trace points directly to the fmt.Println line. The fix is straightforward. Check the pointer before dereferencing it.
func main() {
// path is empty, so LoadConfig returns nil.
cfg := LoadConfig("")
// Guard against nil before touching fields.
if cfg == nil {
fmt.Println("configuration missing")
return
}
// Safe to access fields now.
fmt.Println(cfg.DatabaseURL)
}
Trust the zero value. Check it before you use it.
How the runtime catches it
When your code dereferences a pointer, the Go runtime performs a bounds and validity check. It verifies that the address falls within a mapped memory region. If the address is zero or points to unmapped space, the runtime triggers a panic. It does not return an error. It stops the goroutine and prints a stack trace.
The stack trace lists every function call leading to the crash, newest first. Ignore the runtime internals at the top. Scroll down to your package name. The line numbers tell you exactly where the dereference happened. The function names tell you where the pointer came from. Follow the chain backward. You will usually discover an unhandled error, a missing initialization step, or a branch that forgot to assign a value.
Go prints the panic message inline with the stack trace. You do not need to grep logs or parse JSON. The output is plain text. Read it top to bottom. The first frame inside your code is your starting point.
Goroutines are isolated. A nil pointer panic in one goroutine does not crash the entire process unless you ignore it. You can recover from panics using defer and recover, but you should only do it at known boundaries like HTTP servers or test suites. Let the panic bubble up during development. Fix the root cause instead of masking it.
Realistic example: HTTP handlers and database rows
Web servers and database queries are the most common sources of nil pointer panics. A handler calls a repository method. The repository queries a table. If the row does not exist, the repository returns nil, nil or nil, err. The handler ignores the error and dereferences the result.
package main
import (
"encoding/json"
"net/http"
)
// User represents a database record.
type User struct {
ID int `json:"id"`
Email string `json:"email"`
}
// FindUser simulates a database lookup.
// It returns nil when the ID does not exist.
func FindUser(id int) (*User, error) {
// Return nil to indicate missing record.
if id <= 0 {
return nil, nil
}
// Return a pointer to a populated struct.
return &User{ID: id, Email: "user@example.com"}, nil
}
// handleUser serves a JSON response.
func handleUser(w http.ResponseWriter, r *http.Request) {
// Simulate parsing an ID from the URL.
id := 0
// Call the repository.
u, err := FindUser(id)
if err != nil {
http.Error(w, "internal error", http.StatusInternalServerError)
return
}
// u is nil because id was 0.
// This line panics.
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(u.Email)
}
The panic happens at u.Email. The fix requires treating the return value as a pair. Go functions return multiple values for a reason. The error channel carries the truth. When an error is present, the value is often meaningless. When the error is absent, the value might still be nil if the operation succeeded but found nothing.
func handleUser(w http.ResponseWriter, r *http.Request) {
id := 0
u, err := FindUser(id)
// Check the error first. Go convention puts error handling upfront.
if err != nil {
http.Error(w, "internal error", http.StatusInternalServerError)
return
}
// Check for nil when not found is a valid success state.
if u == nil {
http.Error(w, "user not found", http.StatusNotFound)
return
}
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(u)
}
The pattern is consistent across the standard library. http.Get returns (*Response, error). os.Open returns (*File, error). db.QueryRow returns a *sql.Row that you must scan. Every pointer return demands the same two questions: did it fail, and does it exist?
Error handling in Go is verbose by design. The community accepts the boilerplate because it makes the unhappy path visible. You cannot accidentally swallow an error with a try-catch block. You write the check, or the compiler complains with err declared and not used. Follow the convention. Check errors immediately. Check nil pointers next.
Common traps and compiler hints
Several patterns trigger this panic repeatedly. Recognizing them saves debugging time.
Map lookups return the zero value for the value type, not a pointer. If you store pointers in a map, a missing key returns nil. Accessing a field on that result panics.
m := map[int]*User{}
// m[99] returns nil because the key does not exist.
// m[99].Email panics.
Use the two-value form to check existence. val, ok := m[key]. The ok boolean tells you whether the key was present. Do not guess.
Interface values add another layer. An interface holds a type and a value. An interface can be nil if both are unset. It can also hold a typed nil pointer. var i interface{} = (*User)(nil) is not nil in an if i == nil check. The type is set, but the value is nil. Dereferencing the type assertion result panics. Check the concrete type first, or use a type switch.
The compiler catches some pointer mistakes early. If you try to assign a non-pointer to a pointer variable, you get cannot use x (type int) as *int value in assignment. If you forget to initialize a struct field that is a pointer, the compiler does not warn you. It trusts you. Runtime checks fill the gap.
Slices and maps are already reference types. You rarely need *[]int or *map[string]string. Passing a pointer to a slice adds indirection without benefit. The slice header itself is cheap to copy. Stick to value semantics for slices and maps. Reserve pointers for structs, interfaces, and channels.
Public names start with a capital letter. Private start lowercase. No keywords like public or private. When you define a method on a pointer receiver, use a short name that matches the type. (u *User) Save() is idiomatic. (this *User) Save() is not. The receiver name is usually one or two letters. Keep it consistent.
Accept interfaces, return structs. This mantra reduces unnecessary pointer indirection. If a function only needs to read data, pass the value or a pointer to an interface. If it creates data, return a concrete struct or a pointer to it. Let the caller decide whether to copy or alias.
Decision matrix
Use a direct nil check when a function explicitly returns nil to signal absence or failure. Use the two-value map lookup when you need to distinguish between a missing key and a stored nil pointer. Use a type assertion with the comma-ok idiom when extracting a concrete type from an interface. Use a struct value instead of a pointer when the data is small and never needs to be nil. Use the ok pattern for channel receives to detect closure instead of assuming a value arrives. Use plain sequential code when you don't need pointers: the simplest thing that works is usually the right thing.