Forem: mahdi

Why Is My nil Error Not nil in Go? Unpacking Nil Interfaces

mahdi — Thu, 24 Jul 2025 13:24:47 +0000

If you've written Go for any amount of time, you've probably typed if err != nil hundreds of times. It’s the standard way to handle errors. But sometimes, this check behaves in a way that seems to defy logic, especially when you think you're returning a nil error. This "gotcha" moment almost always comes down to a misunderstanding of how Go's interfaces work, particularly when they are nil.

Let's dive into what a nil interface really is and how to avoid this common pitfall.

What Is an Interface, Really?

First, it's crucial to understand that an interface variable isn't a simple value. It's a container with two parts:

A type: This holds the type of the concrete data stored in the interface (e.g., *bytes.Buffer, *MyError).
A value: This holds the actual value or a pointer to the value (e.g., a pointer to a buffer, nil).

An interface variable is only truly nil when both of these parts are nil. This is the key to the whole mystery.

Let's look at a simple example without even touching errors yet.

package main

import (
    "bytes"
    "fmt"
    "io"
)

func main() {
    // io.Reader is an interface.
    var r io.Reader
    fmt.Println(r == nil) // true

    // bytes.Buffer is a struct
    var b *bytes.Buffer
    fmt.Println(b == nil) // true

    r = b

    // r is now: (type=*bytes.Buffer, value=nil)
    fmt.Println(r == nil) // false
}

When we assign b to r, the interface r gets a type (*bytes.Buffer), so it's no longer considered nil, even though the value it holds is a nil pointer.

The Common error Interface Pitfall

This behavior becomes a real problem when dealing with the error interface. Many people think of error as a built-in primitive type, but it's not. It's an interface defined as:

type error interface {
    Error() string
}

Any type that implements the Error() string method satisfies the error interface. Now, let's see how our new understanding of interfaces can lead to a bug.

Imagine you have a custom error type and a function that might return it.

package main

import "fmt"

type MyError struct {
    Path string
    Msg  string
}

func (e *MyError) Error() string {
    return fmt.Sprintf("%s: %s", e.Path, e.Msg)
}

func processFile(path string) *MyError {

    return nil
}

func main() {

    var err error = processFile("test.txt")


    if err != nil {
        fmt.Printf("Oops, an error occurred: %v\n", err) // This line will run!
        fmt.Printf("Type: %T, Value: %v\n", err, err)
    } else {
        fmt.Println("Everything is fine.")
    }
}

Running this code produces:

Oops, an error occurred: <nil>
Type: *main.MyError, Value: <nil>

The err != nil check passes because the err variable, an error interface, was given a value (nil) that had a concrete type (*MyError). Since the interface's type part was set, the interface itself is no longer nil.

The Solution: Return the Interface

The fix is simple and is a cornerstone of good Go practice: functions should return the error interface type, not a concrete error type.

By changing the function signature, you ensure that when you return nil, you're returning a true nil interface, where both the type and value are nil.

Here’s the corrected code:

package main

import "fmt"

type MyError struct {
    Path string
    Msg  string
}

func (e *MyError) Error() string {
    return fmt.Sprintf("%s: %s", e.Path, e.Msg)
}

func processFileCorrectly(path string) error {
    shouldFail := false 

    if shouldFail {
        return &MyError{Path: path, Msg: "file not found"}
    }


    return nil
}

func main() {
    err := processFileCorrectly("test.txt")

    if err != nil {
        fmt.Printf("Oops, an error occurred: %v\n", err)
    } else {
        fmt.Println("Everything is fine.") // This line runs now!
    }
}

Key Takeaway

A nil pointer to a concrete type is not the same as a nil interface. An interface is only nil if both its internal type and value are nil.

To avoid this trap, always make your functions that can fail return the error type. This way, when you return nil, you're creating a proper "zeroed" interface that will correctly evaluate to true in a == nil check.

Resources

Go Class: 20 Interfaces & Methods in Detail

Interface values with nil underlying values

Nil interface values

Unpacking Go Slices: 3 Common Gotchas You Need to Know

mahdi — Thu, 17 Jul 2025 18:00:09 +0000

Go's slices are a cornerstone of the language, offering a powerful and flexible way to work with sequences of data. However, their internal workings can lead to some surprising behavior if you're not careful. The common phrase "slices are passed by reference" is a helpful simplification, but it's not the whole story and can lead you into traps.

Let's dive into three common "gotchas" that every Go developer should understand to write safer, more predictable code.

1. The append Pitfall: Slices are Passed by Value

It’s a common misconception that passing a slice to a function allows the function to modify the original slice freely. Let's test this with an append operation.

You might expect this code to print [string string2]:

package main

import "fmt"

func update(s []string) {
    s = append(s, "string2") 
}

func main() {
    s := make([]string, 1, 1) 
    s[0] = "string"

    update(s)

    fmt.Println(s) // Output: [string]
}

The Gotcha

The output is [string], not [string string2]. Why?
A slice isn't a direct pointer; it's a small descriptor object called a slice header. This header contains three fields:

1- A pointer to an underlying array where the data is stored.

2- The length of the slice.

3- The capacity of the slice (the total size of the underlying array).

When you pass a slice to a function, you are passing a copy of this header.

In our update function, append sees that the slice's capacity is full (both length and capacity are 1). To add a new element, it must perform a reallocation: it creates a new, larger underlying array and copies the old elements over. The local copy of the slice header s inside update is modified to point to this new array, but the original slice header back in main remains unchanged and still points to the old, smaller array.

The Fix

To make the changes visible to the caller, you must return the (potentially new) slice from the function.

package main

import "fmt"

func update(s []string) []string {
    s = append(s, "string2")
    return s
}

func main() {
    s := make([]string, 1, 1)
    s[0] = "string"

    s = update(s) 

    fmt.Println(s) // Output: [string string2]
}

Key Takeaway:

When a function modifies a slice's length or capacity (e.g., with append), it should always return the modified slice.

2. The Stale Pointer: Risky Business with Element Addresses

Taking a pointer to an element within a slice can be risky if the slice's length changes.

Consider this example where we get a pointer to the first user, alice, and then append a new user to the slice.

package main

import "fmt"

type user struct {
    name  string
    count int
}

func addTo(u *user) {
    u.count++
}

func main() {
    users := []user{{"alice", 0}, {"bob", 0}} // Capacity is 2

    alice := &users[0]

    users = append(users, user{"amy", 0})

    addTo(alice)

    fmt.Println(users) // Output: [{alice 0} {bob 0} {amy 0}]
    fmt.Println(*alice) // Output: {alice 1}
}

The Gotcha

The final users slice shows Alice's count is still 0. The addTo(alice) call modified a version of "alice" that is no longer part of the slice!

Just like in our first example, the append operation caused a reallocation. A new, larger array was created to hold alice, bob, and amy. The users slice variable was updated to point to this new array.

However, our alice pointer is now a stale pointer—it still points to the memory location in the original backing array, which is no longer referenced by the users slice.

Key Takeaway

Avoid holding pointers to slice elements if the slice might be reallocated by operations like append. It's often safer to work with indices.

3. The range Loop Trap: Capturing the Wrong Thing

This is one of the most common gotchas for new Go programmers. When you use a for...range loop, Go uses a single variable to hold the value for each iteration.

// The `thing` variable is reused in each iteration.
for i, thing := range things {
    // thing is a copy of things[i]
}

This reuse can cause chaos when you try to capture a slice or pointer from the iteration variable.

package main

import "fmt"

func main() {
    items := [][2]byte{{1, 2}, {3, 4}, {5, 6}, {7, 8}}
    a := [][]byte{}

    for _, item := range items {
        a = append(a, item[:])
    }

    fmt.Println("Original:", items)
    fmt.Println("Result:", a)
}

Expected Output for a: [[1 2] [3 4] [5 6] [7 8]]
Actual Output for a: [[7 8] [7 8] [7 8] [7 8]]

The Gotcha

The item variable is a single [2]byte array in memory that gets overwritten on each loop. The expression item[:] creates a slice header that points to that memory. Each time we append, we are appending a slice that points to the same memory location. By the time the loop finishes, that memory holds the last value from items, which is {7, 8}. All the slices we appended into a now point to this final value.

The Fix

You must create a true copy of the data for each iteration.

package main

import "fmt"

func main() {
    items := [][2]byte{{1, 2}, {3, 4}, {5, 6}, {7, 8}}
    a := [][]byte{}

    for _, item := range items {
        i := make([]byte, len(item))
        copy(i, item[:])
        a = append(a, i)
    }

    fmt.Println("Original:", items)
    fmt.Println("Result:", a)
}

Expected Output for a: [[1 2] [3 4] [5 6] [7 8]]
Actual Output for a: [[7 8] [7 8] [7 8] [7 8]]

Key Takeaway

When creating slices or pointers from a range loop variable for later use, make sure you are capturing a fresh copy of the data, not a reference to the temporary loop variable itself.

References

Go Slices: Sharing is Caring, Until You Run Out of Room

Parameter Passing in Golang: The Ultimate Truth

Go Class: 14 Reference & Value Semantics

The Unstable Address: A Deep Dive Into Why Go Maps Aren't Directly Modifiable

mahdi — Wed, 16 Jul 2025 12:53:22 +0000

If you've spent any time with Go, you've almost certainly run into this famous compile error: cannot assign to struct field in map. It usually happens when you're trying to do something that feels completely natural.

You have a map of structs, and you just want to change one little thing.

package main

type Book struct {
    Title string
    Pages int
}

func main() {
    library := make(map[string]Book)
    library["gopl"] = Book{Title: "The Go Programming Language", Pages: 380}


    library["gopl"].Pages = 400 //  Error: cannot assign to struct field in map
}

This error can be confusing. Why can't you do this? The answer reveals a core design philosophy of Go: a deep commitment to memory safety and predictability. Let's walk through the "why" and explore the right way to handle this situation.

The Mystery of the Moving Buckets

The root of the issue lies in the nature of Go's maps. A map is a hash table, a dynamic data structure designed for fast lookups. To stay efficient, it needs to be able to grow.

Think of a map as a magical, self-organizing filing cabinet. When you start adding too many files, the cabinet magically adds more drawers and rearranges the existing files to keep everything evenly distributed and easy to find.

This "rearranging" is the key. When a Go map grows, it allocates a new, larger block of memory for its data (called buckets) and moves the existing elements from the old location to the new one.

This means the memory address of a value you place inside a map is not stable. It could be in one place now, and a completely different place later.

The Golden Rule: Addressability

This brings us to Go's golden rule for memory safety: you can only get a pointer to something that has a stable memory location. This "something" is called an addressable value.

Because map elements can move at any time, they are not addressable.

The Go compiler forbids you from taking the address of a map element (&myMap["key"]) to prevent a catastrophic bug: creating a dangling pointer. A dangling pointer is a pointer that points to a memory location that no longer holds the data you expect, leading to unpredictable crashes and data corruption.

The error cannot assign to struct field is the compiler's way of enforcing this rule. Modifying a field (.Pages = 400) requires getting a temporary pointer to the struct, and since the struct is in a map, that's not allowed.

Visualizing The Two Kinds of Maps

Map of Values (The Problematic Case) map[string]Book In this map, the Book structs live directly inside the map's buckets. When the map rearranges its buckets, the data itself moves.

Map of Pointers (The Idiomatic Solution) map[string]*Book Here, the map's buckets only contain pointers. The actual Book structs live elsewhere in a stable location (the heap). When the map rearranges, it only moves the pointers. The data itself stays put.

Because the data's address is stable, you can safely modify it through the pointer.

The Ultimate Proof: Peeking Under the Hood

For those who want to see this rearrangement happen with their own eyes, we can use Go's unsafe package to peek directly at the memory addresses the map uses.

Warning: This code is for demonstration only. Using the unsafe package breaks Go's safety guarantees and should be avoided in production code.

This program prints the memory address of a map's internal "bucket array" before and after forcing it to grow.

package main

import (
    "fmt"
    "reflect"
    "unsafe"
)

type Book struct {
    Index int
    Pages int
}


type hmap struct {
    count     int
    flags     uint8
    B         uint8
    noverflow uint16
    hash0     uint32
    buckets   unsafe.Pointer 
}

func bucketArrayPtr(m interface{}) unsafe.Pointer {
    h := (*hmap)(unsafe.Pointer(reflect.ValueOf(m).Pointer()))
    return h.buckets
}

func main() {
    vm := make(map[int]Book)
    vm[1] = Book{Index: 1}
    fmt.Printf("Value-map buckets @ %p\n", bucketArrayPtr(vm))

    // Force a grow
    for i := 2; i <= 500; i++ {
        vm[i] = Book{Index: i}
    }
    fmt.Printf("Value-map buckets @ %p (after grow)\n\n", bucketArrayPtr(vm))

    pm := make(map[int]*Book)
    pm[1] = &Book{Index: 1}
    heapAddr := pm[1] 

    fmt.Printf("Pointer-map buckets @ %p, Book #1 @ %p\n", bucketArrayPtr(pm), heapAddr)

    // Force a grow
    for i := 2; i <= 500; i++ {
        pm[i] = &Book{Index: i}
    }
    fmt.Printf("Pointer-map buckets @ %p (after grow), Book #1 @ %p\n", bucketArrayPtr(pm), pm[1])
}

The Output and What It Means
When you run this, you'll see something like this:

value-map buckets @ 0xc00010c000
value-map buckets @ 0xc00012a000 (after grow)

pointer-map buckets @ 0xc000138000, Book#1 @ 0xc00000a0f0
pointer-map buckets @ 0xc000150000 (after grow), Book#1 @ 0xc00000a0f0

1- Value-Map: The bucket address changed. This is definitive proof that the data stored inside the map moved.

2- Pointer-Map: The bucket address changed, but the address of Book #1 on the heap stayed exactly the same.

This code provides concrete evidence of our theory. The map's internal storage is unstable, but the data you point to from within it can be perfectly stable.

The Solutions: Two Ways Forward

So, how do you fix the original code?

Solution 1: The "Copy-Modify-Replace" Pattern

If you must use a map of values, you have to follow this three-step dance:

1- Copy the struct out of the map into a temporary variable.

2- Modify the temporary variable.

3- Replace the value in the map with your modified copy.

library := make(map[string]Book)
library["gopl"] = Book{Title: "The Go Programming Language", Pages: 380}

tmp := library["gopl"]   // 1. Copy
tmp.Pages = 400          // 2. Modify
library["gopl"] = tmp    // 3. Replace

This works, but it's verbose and can be inefficient if the struct is large.

Solution 2: The Go Way - Use Pointers

The more common and idiomatic solution is to simply store pointers in your map from the beginning.

library := make(map[string]*Book)
library["gopl"] = &Book{Title: "The Go Programming Language", Pages: 380}

library["gopl"].Pages = 400

This is cleaner, more efficient, and communicates your intent to modify the values.

Conclusion: A Feature, Not a Bug

The inability to directly modify a value in a map isn't a flaw in Go; it's a deliberate design decision. A look at the Go team's internal discussions (like GitHub Issue #3117) shows they chose predictability and memory safety over a minor syntactic convenience.

So the next time you encounter this error, don't see it as a limitation. See it as Go protecting you from a whole class of subtle, dangerous bugs. It's a reminder to be explicit about your data, leading to code that is safer, clearer, and easier to reason about.

Resources

Issue #3117

Addressable values in Go (and unaddressable ones too)

Go Class: 12 Structs, Struct tags & JSON

Go Slices: Sharing is Caring, Until You Run Out of Room

mahdi — Tue, 15 Jul 2025 15:48:34 +0000

In this post, we will demonstrate the relationship between a slice and its underlying array. To explain this concept, we'll use a code example and walk through it step-by-step.

func main() {
    var a [3]int = [3]int{1, 2, 3}
    b := a[0:1]
    c := a[0:2]

    b = append(b, 4)                 // grows b, mutates a
    fmt.Printf("a[%p]= %v\n", &a, a) // a[0xc0000121f8]= [1, 4, 3]
    fmt.Printf("b[%p]= %[1]v\n", b)  // b[0xc0000121f8]= [1, 4]

    c = append(c, 5)                 // grows c, mutates a
    fmt.Printf("a[%p]= %v\n", &a, a) // a[0xc0000121f8]= [1, 4, 5]
    fmt.Printf("c[%p]= %[1]v\n", c)  // c[0xc0000121f8]= [1, 4, 5]

    c = append(c, 6)                 // because cap c is 3, this operation forces to reallocate c with doubling cap
    fmt.Printf("a[%p]= %v\n", &a, a) // a[0xc0000121f8]= [1, 4, 5]
    fmt.Printf("c[%p]= %[1]v\n", c)  // c[0xc0000145d0]= [1, 4, 5, 6]
    fmt.Println("cap c: ", cap(c))   // cap c: 6

    c[0] = 9                         // mutates a different array!
    fmt.Printf("a[%p]= %v\n", &a, a) // a[0xc0000121f8]= [1, 4, 5]
    fmt.Printf("c[%p]= %[1]v\n", c)  // c[0xc0000145d0]= [9, 4, 5, 6]

}

1-initialization:

So when we define a, b and c we some something like this image.

As we can see a is an array and b, c is slices that a is their underlying array.

2- b = append(b, 4)

• b has a length of 1 and a capacity of 3. There is room to add elements.
• No reallocation is needed. The append operation adds the value 4 into the next available spot in the underlying array a.
• This overwrites a[1].
• a is mutated.

3- c = append(c, 5)

• c has a length of 2 and a capacity of 3. There is still room.
• No reallocation is needed. The append adds 5 into the next spot in the underlying array a.
• This overwrites a[2].
• a is mutated again.

4- c = append(c, 6)

• c now has a length of 3 and a capacity of 3. There is no more room.
• To add 6, append must perform a reallocation.
• It creates a new, larger array (with a new capacity, typically doubled to 6), copies the elements [1, 4, 5] over, and then appends 6.
• The slice c is updated to point to this new array. It no longer shares data with a.
• a is not affected.

5- c[0] = 9

• This modifies the first element of the slice c.
• Since c now points to its own separate, underlying array, this change only affects c.
• a remains completely untouched.

code output

a[0xc0000121f8]= [1 4 3]
b[0xc0000121f8]= [1 4]
a[0xc0000121f8]= [1 4 5]
c[0xc0000121f8]= [1 4 5]
a[0xc0000121f8]= [1 4 5]
c[0xc0000145d0]= [1 4 5 6]
cap c:  6
a[0xc0000121f8]= [1 4 5]
c[0xc0000145d0]= [9 4 5 6]

The memory addresses shown in the output (like 0xc0000121f8) are specific to a single execution of the program. When you run the code on your machine, the operating system will allocate memory at different addresses.

Resources

Go Class: 10 Slices in Detail

A Practical Guide to Defer, Panic, and Recover in Go

mahdi — Mon, 14 Jul 2025 21:11:31 +0000

How do we guarantee that a cleanup task, like closing a file or unlocking a mutex, always gets done in our Go programs? This is a critical question for writing robust and reliable software. Fortunately, Go provides a powerful and elegant set of tools for this: the defer, panic, and recover keywords.
Let's dive into how to use them effectively.

The Magic of defer

The defer statement schedules a function call to be executed just before the function it's in returns. It's the simplest way to guarantee that something happens, no matter how the function exits.

Common use cases include:

Closing a file handle
Closing a network connection
Unlocking a mutex

Here’s a classic example of using defer to ensure a file is closed:

package main

import (
    "fmt"
    "log"
    "os"
)

func main() {
    f, err := os.Open("my_file.txt")
    // IMPORTANT: Always check for the error before deferring!
    // If os.Open fails, 'f' will be nil, and calling f.Close() would cause a panic.
    if err != nil {
        log.Fatal(err)
    }
    // This call to f.Close() is now guaranteed to run when main() exits.
    defer f.Close()

    // ... and now we can do something with the file ...
    fmt.Println("File opened successfully. Deferring the close.")
}

A key thing to remember is that defer is function-scoped, not block-scoped. It doesn't matter if the defer is inside an if block or a for loop; the deferred call will only execute when the entire function returns. This can lead to a common gotcha.

The defer in a Loop Gotcha
Consider opening multiple files in a loop:

// Warning: This code has a potential bug!
func processFiles(filenames []string) {
    for _, filename := range filenames {
        f, err := os.Open(filename)
        if err != nil {
            log.Printf("failed to open %s: %v", filename, err)
            continue
        }

        // This will NOT close the file at the end of the loop iteration.
        // It will wait until processFiles() returns.
        defer f.Close()

        // ... do work with f ...
    }
}

In the code above, the f.Close() calls are all queued up and will only run when the processFiles function finishes. If you're processing a large number of files, you could easily run out of available file descriptors, crashing your program.

The solution is to either call Close() explicitly at the end of the loop or refactor the loop's body into its own function, where defer can work as intended.

Panic! And the Unwinding Stack

A panic is a built-in function that stops the ordinary flow of control. It's typically used to signal a truly unexpected and unrecoverable error.

When a function panics, its execution stops immediately. However, any deferred functions are still executed before the program unwinds the call stack. Deferred calls are executed in LIFO (Last-In, First-Out) order.

Let's see this in action with a recursive function:

package main

import "fmt"

func main() {
    f()
    fmt.Println("Returned normally from f.")
}

func f() {
    fmt.Println("Calling g.")
    g(0)
    // This line is never reached because g panics.
    fmt.Println("Returned normally from g.")
}

func g(i int) {
    if i > 3 {
        fmt.Println("Panicking!")
        panic(fmt.Sprintf("%v", i)) // Panic when i is 4
    }
    // This defer is pushed onto the stack for each call to g.
    defer fmt.Println("Defer in g", i)
    fmt.Println("Printing in g", i)
    g(i + 1)
}

When you run this, the flow is:

1- main calls f.

2- f calls g(0), which calls g(1), then g(2), then g(3).

3- Each call to g prints "Printing in g..." and defers its "Defer in g..." message.

4- g(3) calls g(4), which triggers the panic.

5- The panic stops normal execution and starts unwinding the stack.

6- As each g function call exits due to the panic, its deferred fmt.Println is executed in LIFO order.

The output will be:

Calling g.
Printing in g 0
Printing in g 1
Printing in g 2
Printing in g 3
Panicking!
Defer in g 3
Defer in g 2
Defer in g 1
Defer in g 0
panic: 4

goroutine 1 [running]:
...

Notice how the deferred statements ran in reverse order (3, 2, 1, 0) after the panic started.

recover: Taming the Panic

What if we want to catch a panic and handle it gracefully instead of letting it crash our program? This is where recover comes in.

recover is a built-in function that regains control of a panicking goroutine. The golden rule is that recover is only useful when called directly inside a deferred function.

Let's modify our previous example to recover from the panic in function f:

package main

import "fmt"

func main() {
    f()
    // Because we recovered, the program now finishes normally.
    fmt.Println("Returned normally from f.")
}

func f() {
    // Defer a function that will run when f exits.
    defer func() {
        // recover() checks if the program is panicking.
        if r := recover(); r != nil {
            // It catches the value passed to panic() and stops the panic.
            fmt.Println("Recovered in f:", r)
        }
    }()

    fmt.Println("Calling g.")
    g(0) // This call will panic.
    // This line is still never reached.
    fmt.Println("Returned normally from g.")
}

// g() function is the same as before
func g(i int) {
    if i > 3 {
        fmt.Println("Panicking!")
        panic(fmt.Sprintf("%v", i))
    }
    defer fmt.Println("Defer in g", i)
    fmt.Println("Printing in g", i)
    g(i + 1)
}

Now, the program's flow changes:

1- The execution proceeds as before, ending with a panic in g(4).

2- The stack unwinds, and the deferred calls in g are executed.

3- The panic propagates up to f.

4- Before f exits, its deferred function is executed.

5- Inside that deferred function, recover() catches the panic value ("4"), stops the panicking sequence, and allows f to return normally.

6- Execution continues in main, which now prints its final line.

The new output is:

Calling g.
Printing in g 0
Printing in g 1
Printing in g 2
Printing in g 3
Panicking!
Defer in g 3
Defer in g 2
Defer in g 1
Defer in g 0
Recovered in f: 4
Returned normally from f.

As you can see, the program no longer crashes.

While recover is powerful, it should be used carefully. A good use case is in a web server, where you might want to recover from a panic in a single HTTP request handler without crashing the entire server. In most cases, however, it's better to use Go's standard error values for error handling.

Summery

Use defer for cleanups that must run at function exit (closing files, unlocking mutexes).
Avoid deferring inside tight loops—it defers until function exit, not loop exit.
Check errors first, then defer the cleanup.

Resouces

Parameter Passing in Golang: The Ultimate Truth

mahdi — Thu, 10 Jul 2025 00:02:54 +0000

We often learn that Go parameters are either passed by value or by reference. For example, basic types (ints, bools, etc.), arrays and structs are “by value,” while things like pointers, slices, maps, and channels are often called “by reference.” In practice this terminology can be misleading. In Go, every function parameter is passed by value (i.e. copied). That copy might be a simple value (for an int or an array) or a more complex descriptor (for a slice, string, or map).

Passed by value: numbers, booleans, arrays, structs, etc. (the entire value is copied)
Reference-like types: pointers, strings, slices, maps, channels (the pointer or descriptor is copied)

Let’s walk through some examples to see what really happens.

Passing an Array (By Value)

func do(b [3]int) int {
    b[0] = 0
    return b[1]
}

func main() {
    a := [3]int{1, 2, 3}
    v := do(a)
    fmt.Println(a, v)  // [1 2 3] 2
}

In this example, do takes a fixed-size array b [3]int. When we call do(a), Go makes a copy of a and passes it to do. Inside do, setting b[0] = 0 only affects the copied array, not the original. This is why after calling do, the original a is still [1 2 3]. As the Go blog explains, “when you assign or pass around an array value you will make a copy of its contents.” (If you want to modify the caller’s array, you’d have to pass a pointer to the array, e.g. * [3]int.)

Passing a Map (Pointer-Like Behavior)

func do(m1 map[int]int) {
    m1[3] = 1
    m1[4] = 3
}

func main() {
    m := map[int]int{4: 2}
    fmt.Println(m)  // map[4:2]
    do(m)
    fmt.Println(m)  // map[3:1 4:3]
}

Here, do takes a map. Internally, a Go map is implemented as a pointer to a runtime hash table structure. When we call do(m), Go copies the map descriptor (which is effectively a pointer) and passes it to do. The code m1[3] = 1 then mutates the underlying hash table. Because the descriptor copy still points to the same map data, the original map m in main sees the changes. In other words, the argument m and the parameter m1 both refer to the same map in memory. As Alex Edwards notes, Go “implements a map as a pointer to a runtime.hmap struct,” so passing a map to a function gives you a copy of that pointer – modifying the map will mutate the original data.

The Slice Puzzle: Append and Capacity

func do(b []int) int {
    b = append(b, 4)
    b[0] = 0
    return b[1]
}

func main() {
    a1 := []int{1, 2, 3}
    fmt.Printf("len %d cap %d\n", len(a1), cap(a1))  // len 3 cap 3
    v1 := do(a1)
    fmt.Println(a1, v1)  // [1 2 3] 2
}

Many people expect slices to behave like maps in the previous example (with changes showing up outside). But here, after calling do(a1), the slice a1 is still [1 2 3]. What happened? Remember that a slice value in Go is itself a 3-word descriptor: it contains a pointer to an underlying array, a length, and a capacity. In our example, a1 := []int{1,2,3} has length 3 and capacity 3. Inside do, we do b = append(b, 4). Since the capacity of b was only 3, append allocates a new underlying array (with larger capacity), copies the old elements over, and returns a new slice header with that new array pointer. Then b[0] = 0 writes to this new array. Meanwhile, the original slice a1 in main still points to the old array (which was untouched). In short, the append caused a reallocation, so b inside do ended up pointing to a different array than a1 does. The assignment b[0] = 0 did not affect a1’s data. As Alex Edwards explains, the slice returned by append “may or may not point to the same underlying array” depending on capacity. If it allocates a new array, the function’s copy of the slice header is changed without affecting the caller’s slice. This is why a1 remains [1 2 3] even though do returned 0 at index 1 of its (new) slice.
All Parameters Are Passed By Value
The key insight is: Go always copies the function arguments. The phrase “pass-by-value” means every argument is copied. There is no hidden “pass-by-reference” semantics in Go. Even when we passed a pointer, a slice, or a map, the pointer or descriptor was copied by value. As Alex Edwards emphasizes, “parameters are always a copy of the arguments. That is, they are always passed by value.”.

In other words, a function parameter is never an alias for the caller’s variable. The only way a function can change the caller’s variable is if the caller passes in something like a pointer and the function dereferences it to write through to the original data.

Descriptors for Strings, Slices, and Maps

In Go’s runtime, complex types like strings, slices, and maps are built on small header (descriptor) values that contain pointers under the hood. For example, a Go string is a two-word struct: a pointer to the UTF-8 data and a length. A slice is a three-word struct: a pointer to the first element of an array, the slice length, and the slice capacity. A map is not described by just a few words in Go code, but internally it’s a pointer to a runtime hash table. Thus, when you pass a map or channel to a function, you are copying that pointer-like header. Any element writes (like m1[3]=...) update the shared data. Notice that in each case, what gets copied is the header or pointer, not the entire contents. So when we say slices or maps are “reference types,” we mean their headers contain pointers to shared data. But the headers themselves are passed by value (copied) into functions.

Passing a Pointer to a Slice

func do(b *[]int) int {
    *b = append(*b, 4)
    (*b)[0] = 0
    return (*b)[1]
}

func main() {
    a1 := []int{1, 2, 3}
    fmt.Printf("len %d cap %d\n", len(a1), cap(a1))  // len 3 cap 3
    v1 := do(&a1)
    fmt.Println(a1, v1)  // [0 2 3 4] 2
}

What if we really want the function to be able to grow the caller’s slice? Here do takes a pointer to a slice (*[]int). Now, inside do we do *b = append(*b, 4) – this dereferences the pointer and reassigns the caller’s slice variable to the new slice value returned by append. Then (*b)[0] = 0 writes to the shared array. When we run this, the output shows a1 has become [0 2 3 4]. By passing &a1, we gave do the address of the slice header. Any assignment to *b actually updates a1 in main. As the official blog notes, writing *s = append(*s, …) will be “written-through to the memory address of the scores argument”. In other words, using a pointer-to-slice parameter forces append and other reassignments to affect the original slice variable.

Conclusion

To summarize:

Go always passes function arguments by value. Even a pointer, slice, map or channel parameter is still a copy of whatever header or pointer you passed in. There is no hidden pass-by-reference mechanism.
Basic types, arrays, structs: Passing them copies the entire value. Mutating the parameter never changes the caller’s variable unless you passed a pointer to it.
Slices, maps, channels: Each has an internal header (pointer + length/capacity or pointer to a hash table). Passing one of these copies the header. Mutations to the underlying data (e.g. setting a slice element or a map entry) affect the original data structure. However, reassigning the slice or map (like b = append(b,…) or m = make(map…)) only changes the local copy of the header, not the caller’s copy.
Strings: Immutable, but a string header (pointer + length) is also passed by value. Slicing a string creates a new header pointing into the same data.

In short, don’t think in terms of “Go passes this by reference.” Think of it as “Go copies values,” and the effect depends on what those values are. If the value contains a pointer to shared data (as in slices or maps), then functions can mutate that shared data. If you need a function to update a variable itself (like extend a slice or change a struct), you must pass a pointer to it. This understanding will help avoid confusing surprises and make your Go code behavior predictable.