A.4 Troubleshooting Guide

This section helps you diagnose and fix common issues in Go programs.

Common Errors and Solutions

1. "undefined: X" Error

Problem

undefined: functionName

Causes

• Function not defined
• Wrong package imported
• Typo in function name
• Function not exported (lowercase)

Solutions

// Check function exists
func functionName() { }

// Check package import
import "package/name"

// Check capitalization (exported functions start with capital)
func FunctionName() { }  // Exported
func functionName() { }  // Not exported

2. "cannot use X (type Y) as type Z" Error

Problem

cannot use x (type int) as type string

Causes

• Type mismatch
• Missing type conversion
• Wrong function signature

Solutions

// Explicit type conversion
var x int = 42
var s string = strconv.Itoa(x)  // Convert int to string

// Check function signature
func process(s string) { }
process(strconv.Itoa(x))  // Correct

3. "imported and not used" Error

Problem

imported "package" and not used

Solutions

// Remove unused import
// Or use blank identifier
import _ "package"  // Import for side effects only

4. "declared and not used" Error

Problem

x declared and not used

Solutions

// Use the variable
_ = x  // Explicitly ignore

// Or remove if truly unused

5. "nil pointer dereference" Panic

Problem

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

Causes

• Accessing field/method on nil pointer
• Uninitialized pointer

Solutions

// Check for nil before use
if p != nil {
    p.DoSomething()
}

// Initialize pointer
p := &MyStruct{}
// or
p := new(MyStruct)

6. "index out of range" Panic

Problem

panic: runtime error: index out of range [5] with length 3

Causes

• Accessing slice/array index that doesn't exist
• Off-by-one errors

Solutions

// Check bounds before access
if i < len(slice) {
    value := slice[i]
}

// Use range for iteration
for i, v := range slice {
    // Safe: i is always valid
}

7. "send on closed channel" Panic

Problem

panic: send on closed channel

Causes

• Sending to closed channel
• Race condition with channel closing

Solutions

// Check if channel is closed
select {
case ch <- value:
    // Sent successfully
case <-done:
    // Channel closed or done signal
}

// Use recover for graceful handling
defer func() {
    if r := recover(); r != nil {
        // Handle panic
    }
}()

Debugging Tips

1. Use Print Statements

fmt.Printf("Debug: value = %v\n", value)
fmt.Printf("Debug: at line %d\n", __LINE__)  // Use runtime.Caller

Why print statements help

• Quick debugging: Fast way to see values
• No setup: Works immediately
• Simple: Easy to add and remove

2. Use Delve Debugger

# Install Delve
go install github.com/go-delve/delve/cmd/dlv@latest

# Debug program
dlv debug ./main.go

# Common commands
break main.main    # Set breakpoint
continue          # Continue execution
next              # Next line
print variable    # Print variable value

Why Delve is powerful

• Full debugging: Breakpoints, step through code
• Inspect state: See variable values
• Goroutine debugging: Debug concurrent code

3. Use go vet

go vet ./...

Why go vet helps

• Static analysis: Finds issues before runtime
• Common mistakes: Catches many bugs
• Best practices: Enforces Go idioms

4. Use Race Detector

go test -race ./...
go run -race main.go

Why race detector is essential

• Concurrency bugs: Finds race conditions
• Data races: Detects shared memory issues
• Debugging: Helps debug concurrent code

5. Use Logging

import "log"

log.Printf("Processing item %d", i)
log.SetFlags(log.LstdFlags | log.Lshortfile)

Why logging helps

• Production debugging: Debug in production
• Trace execution: Follow program flow
• Context: Add context to errors

6. Use pprof for Profiling

go tool pprof http://localhost:6060/debug/pprof/profile

Why profiling helps

• Performance issues: Find bottlenecks
• Memory leaks: Detect memory issues
• Optimization: Know what to optimize

Performance Issues

1. High Memory Usage

Symptoms

• Program uses excessive memory
• GC runs frequently
• Out of memory errors

Diagnosis

go tool pprof http://localhost:6060/debug/pprof/heap

Solutions

• Reduce allocations
• Use sync.Pool for temporary objects
• Pre-allocate slices
• Check for memory leaks

2. Slow Execution

Symptoms

• Program runs slowly
• High CPU usage
• Long response times

Diagnosis

go tool pprof http://localhost:6060/debug/pprof/profile

Solutions

• Profile to find bottlenecks
• Optimize hot paths
• Reduce allocations
• Use appropriate algorithms

3. Frequent GC Pauses

Symptoms

• Periodic pauses
• High GC overhead
• Latency spikes

Diagnosis

import "runtime"

var m runtime.MemStats
runtime.ReadMemStats(&m)
fmt.Printf("GC runs: %d\n", m.NumGC)

Solutions

• Reduce allocations
• Reuse objects
• Adjust GOGC environment variable
• Use object pooling

Concurrency Issues

1. Race Conditions

Symptoms

• Non-deterministic behavior
• Incorrect results
• Data corruption

Diagnosis

go test -race ./...

Solutions

• Use channels for communication
• Use mutexes for shared state
• Avoid shared mutable state
• Use atomic operations for simple cases

2. Deadlocks

Symptoms

• Program hangs
• No progress
• All goroutines blocked

Diagnosis

import "runtime"

fmt.Printf("Goroutines: %d\n", runtime.NumGoroutine())

Solutions

• Use timeouts in select statements
• Avoid circular dependencies
• Use context for cancellation
• Check lock ordering

3. Goroutine Leaks

Symptoms

• Memory usage grows over time
• Increasing number of goroutines
• Program slows down

Diagnosis

// Monitor goroutine count
for {
    fmt.Printf("Goroutines: %d\n", runtime.NumGoroutine())
    time.Sleep(1 * time.Second)
}

Solutions

• Provide exit mechanisms
• Use context for cancellation
• Close channels properly
• Wait for goroutines to complete

4. Channel Leaks

Symptoms

• Goroutines waiting forever
• Memory not freed
• Program hangs

Solutions

• Always close channels when done
• Use buffered channels appropriately
• Drain channels properly
• Use select with timeout

Common Debugging Workflows

1. Debugging Crashes

# Get stack trace
go run main.go 2>&1 | tee crash.log

# Use GOTRACEBACK
GOTRACEBACK=all go run main.go

2. Debugging Performance

# CPU profile
go test -cpuprofile=cpu.prof ./...
go tool pprof cpu.prof

# Memory profile
go test -memprofile=mem.prof ./...
go tool pprof mem.prof

3. Debugging Concurrency

# Race detector
go test -race ./...

# Goroutine dump
kill -QUIT <pid>  # Sends SIGQUIT, prints goroutine dump

4. Debugging Build Issues

# Verbose build
go build -v

# See commands
go build -x

# Check environment
go env

Getting Help

1. Read Error Messages

Go error messages are usually helpful. Read them carefully.

2. Check Documentation

go doc package
go doc package.Function

3. Search Go Issues

• GitHub: github.com/golang/go/issues
• Stack Overflow: stackoverflow.com/questions/tagged/go
• Go Forum: forum.golangbridge.org

4. Use go vet and gofmt

go vet ./...
gofmt -d .

5. Minimal Reproducible Example

When asking for help, provide:

• Minimal code that reproduces the issue
• Go version
• Error message
• Expected vs actual behavior

Troubleshooting is a skill that improves with experience. Use these tools and techniques to systematically diagnose and fix issues in your Go programs.

Previous: A.3 Common Patterns and Idioms Next: A.5 Resources and Further Reading