Go Gotchas That Cost Me Hours (Learn From My Pain)

Go has burned me more than once. With bugs that felt like the language was glitching:

Channels that blocked after I’d “fixed” the blocking. Functions that kept running after hitting an error. Slices that printed data that seemingly came out of nowhere.

But as I’ve come to learn, every single time, Go was doing exactly what I asked. I just didn’t fully understand what I was asking for.

So in this article I want to share some of the “gotchas” that have cost me an embarrassing amount of time, simply because I didn’t fully understand how the language and its idioms worked.

I hope they save you some hours of pain.

Gotcha 1: Channels don't eliminate blocking. They move it.

A little while ago, I was building a mini tool that turns Linux’s Netcat into a group chat tool. Simple enough idea: multiple clients connect, one sends a message, everyone gets it. Like a mini-terminal-based WhatsApp group.

The problem with that is I ended up writing to multiple network connections (i.e., ”sending messages”) in my main loop. Which runs the risk of a slow client blocking the whole server.

func broadcast(clients []*Client, msg string) {
    for _, client := range clients {
        // writing directly to the network connection
        // a slow client blocks everyone behind it
        fmt.Fprintln(client.conn, msg)
    }
}

So I did what felt like the obvious fix: give each client their own messages channel. That way I'm not writing to slow network connections in the main loop anymore.

type Client struct {
    conn     net.Conn
    messages chan string
}

Each client handler reads from its channel and writes to the connection. No blocking in the main loop.

Or so I thought.

Turns out however, a slow client could still block my server.

Here's why. The channel I created was unbuffered:

messages: make(chan string)

An unbuffered channel blocks the sender until the receiver reads from it. So if a client handler was slow writing to the network, it stopped reading from the channel. Which meant the main loop sending to that channel blocked. Which meant every other client stalled too.

I'd just pushed the blocking one step further. From the network write, into the channel send.

// main loop broadcasting to all clients
for _, client := range clients {
    client.messages <- msg // still blocks if the client handler is slow
}

To really fix it, I had to

1. Give the channel a reasonable buffer size (so it could accept multiple messages without blocking)

messages: make(chan string, 10)

1. Add a timeout for really slow clients (cause buffers can still get full)

select {
case client.messages <- msg:
    // sent
case <-time.After(time.Second):
    // client too slow, skip or disconnect
}

Channels are great for avoiding race conditions when you’ve got concurrent code. But they, and goroutines, don’t magically fix bottlenecks.

I’d basically been running a sort of mental shortcut where goroutines + channels = fast safe code.

But that gets you into issues like this.

Gotcha 2: Slicing doesn't copy. And that will ruin your day.

This one made me want to pull my hair out. I spent a whole hour, in a coding test, staring at my code, running it again and again, trying to figure out why I was getting weird outputs.

See what I’d done was something like this:

alt := rev1[:by]
rev1 = rev1[by:]

I split a slice in two. And then later looped through my rev1 slice while appending to alt.

for _, v := range rev1 {
    alt = append(alt, v)
}

But here’s the thing.

Slicing in Go doesn’t make a copy. It just creates a small header pointing to the same underlying array. So alt and rev1 were sharing memory.

original := []int{1, 2, 3, 4, 5}
alt := original[:2]  // [1, 2] — but still pointing at the same array
rev1 := original[2:] // [3, 4, 5] — same array, different window

So when I appended to alt, Go wrote into the array that rev1 was also pointing at. Which meant the slice I was iterating over was being modified while I was iterating over it.

So the values kept changing.

Leading to my weird outputs.

The fix is to force each slice onto its own backing array. The cleanest way to do that is to append data from one slice into the other. append() copies data from one slice to the other, giving each slice its own backing array. It’s own chunk of memory, if you will.

alt := append([]int{}, rev1[:by]...)

It's one of those things that makes total sense once you understand how slices work under the hood. But until you do, it’s a head-scratcher.

Gotcha 3: make() with a length isn't an empty slice.

This one got me twice. Same bug, same confusion, different day.

I needed a slice to collect some values, so I did what felt natural:

results := make([]int, 3)

Then later appended to it:

results = append(results, 42)

And ended up with:

[0, 0, 0, 42]

Not [42]. Not what I wanted.

Here's the thing. make([]int, 3) doesn't give you an empty slice with room for 3 elements. It gives you a slice with 3 elements already in it, all set to their zero value. When you append, Go doesn't replace those zeros. It adds your values after them.

If you want an empty slice with preallocated capacity, the second argument to make is length, and there's a third for capacity:

results := make([]int, 0, 3) // length 0, capacity 3
results = append(results, 42) // [42]

Or just use a nil slice if you don't need to preallocate:

var results []int
results = append(results, 42) // [42]

The distinction between length and capacity can be a somewhat unclear at first. Length is how many elements are in the slice right now. Capacity is how much room the underlying array has before Go needs to allocate a new one.

Gotcha 4: Forgetting to return after handling an error.

This one is less of a language quirk and more of a habit you have to build. But it's bitten me enough times to earn its spot here.

It goes like this. You're in an error block, you do something (log it, append to a slice, whatever) and then you just move on, forget to add a return statement.

func process(data []string) ([]Result, error) {
    var results []Result

    parsed, err := parse(data)
    if err != nil {
        log.Println("parse error:", err)
        // forgot to return here
    }

    // keeps running with a broken `parsed`
    for _, item := range parsed {
        results = append(results, transform(item))
    }

    return results, nil
}

The function keeps running with broken state. And then something fails way down the line in a completely different function, and you spend twenty minutes tracing backwards trying to figure out why.

The fix is just the habit. return is part of the error block, always:

if err != nil {
    log.Println("parse error:", err)
    return nil, err
}

Same thing applies with break and continue in loops. If your logic depends on stopping or skipping after a condition, make sure you're actually telling Go to stop or skip.

Truth be told though, even with this warning, this one will probably still get you a few times before your OCD finally kicks in and forces you to check every every error block you write.

---

Ones I Caught Before They Caught Me

These two didn't burn me the way the others did. I came across them early enough to file them away before making the mistake. I’m passing them on for the same reason.

Loop variable capture in goroutines

If you spin up goroutines inside a loop and reference the loop variable inside them, all the goroutines might end up using the same value, i.e., the final one the loop landed on.

items := []string{"book", "pen", "eraser"}

for _, v := range items {
    go func() {
        fmt.Println(v) // all goroutines might print "eraser"
   }()
}

This happens because the goroutines close over v itself (see closures), not its value at the time the goroutine was created. By the time they run, the loop may have already finished.

The fix is to pass the value as an argument:

for _, v := range items {
    go func(val string) {
        fmt.Println(val) // each goroutine gets its own copy
    }(v)
}

Worth knowing: Go 1.22 changed loop variable semantics so each iteration gets its own variable. If you're on a recent version this is less of a landmine. But a lot of codebases are still on older versions, so it's worth understanding either way.

defer in a loop

defer doesn't run at the end of each loop iteration. It runs when the surrounding function returns.

for _, path := range files {
    f, err := os.Open(path)
    if err != nil {
        continue
    }
    defer f.Close() // won't close until the whole function exits
}

If you're opening files in a loop and deferring their close, you'll hold all of them open until the function returns. On a long-running loop that's a resource leak waiting to happen.
The fix is to wrap the body in a helper function, so defer behaves the way you intended:

func processFile(path string) error {
    f, err := os.Open(path)
    if err != nil {
        return err
    }
    defer f.Close() // now closes when processFile returns
    // ...
}

for _, path := range files {
    processFile(path)
}

These won't be the last ones.

Go has a way of humbling you just when you think you've got a handle on it. I've fixed these bugs, written them down, but I'm certain there's a new one waiting for me in code I haven't written yet.

But while every one of these cost me time, but they also left me with a clearer picture of how the language actually works under the hood. The slice bug taught me more about memory than any article I'd read on the topic. The channel bug forced me to actually think about concurrency instead of just reaching for goroutines by habit.

So if you're hitting weird bugs in Go right now, good. Trace through them. Write them down. They're likely teaching you something.

And if you've got your own, comment them below. I'm still collecting.