Introduction

The Go toolchain caches compiled packages in $GOCACHE to speed up subsequent builds. When a build is interrupted (OOM kill, power loss, disk full, CI pod eviction), cached artifacts can become corrupted. The next build may fail with strange compilation errors, hash mismatches, or stale output even though the source code is correct.

Symptoms

  • go build fails with: open /home/user/.cache/go-build/ab/abcd1234-a: no such file or directory
  • go: build output "main" already exists and is not an object file
  • Stale compilation results: changes to source code not reflected in build
  • go build -a works but go build fails
  • verifying go.mod: ... checksum mismatch
  • Error persists across go clean but not across rm -rf $GOCACHE
bash
go build github.com/myorg/myservice:
# github.com/myorg/myservice/internal/handler
open /root/.cache/go-build/3f/3f7b5a1c8d9e2f4a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a-d:
input/output error

Common Causes

  • CI runner killed by OOM during build
  • Disk full during cache write
  • Docker volume mount with inconsistent permissions
  • Network filesystem (NFS) causing write interruptions
  • Multiple concurrent Go builds writing to the same cache

Step-by-Step Fix

  1. 1.Clear the build cache:
  2. 2.```bash
  3. 3.# Clear all cached artifacts
  4. 4.go clean -cache

# Clear test cache specifically go clean -testcache

# Clear module cache (re-downloads dependencies) go clean -modcache

# Or manually remove the entire cache rm -rf $(go env GOCACHE) rm -rf $(go env GOMODCACHE) ```

  1. 1.Verify cache location and health:
  2. 2.```bash
  3. 3.# Show cache locations
  4. 4.go env GOCACHE # /home/user/.cache/go-build
  5. 5.go env GOMODCACHE # /home/user/go/pkg/mod
  6. 6.go env GOMOD # /path/to/go.mod

# Check cache size du -sh $(go env GOCACHE) du -sh $(go env GOMODCACHE) ```

  1. 1.Force rebuild from scratch:
  2. 2.```bash
  3. 3.# -a forces rebuilding all packages
  4. 4.go build -a ./...

# -gcflags=-l disables inlining (debugging) go build -gcflags=all=-l ./...

# -work prints the temporary work directory go build -work ./... ```

  1. 1.Configure cache for CI environments:
  2. 2.```yaml
  3. 3.# GitHub Actions - cache Go build artifacts
  4. 4.- name: Cache Go build
  5. 5.uses: actions/cache@v4
  6. 6.with:
  7. 7.path: |
  8. 8.~/.cache/go-build
  9. 9.~/go/pkg/mod
  10. 10.key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
  11. 11.restore-keys: |
  12. 12.${{ runner.os }}-go-
  13. 13.`
  14. 14.Set custom cache location:
  15. 15.```bash
  16. 16.# Use a dedicated cache directory
  17. 17.export GOCACHE=/tmp/go-build-cache
  18. 18.export GOMODCACHE=/tmp/go-mod-cache

# In Dockerfile ENV GOCACHE=/tmp/.cache/go-build ENV GOMODCACHE=/tmp/.cache/go-mod RUN mkdir -p $GOCACHE $GOMODCACHE ```

Prevention

  • Run go clean -cache as part of CI cleanup step
  • Monitor disk space before builds: df -h $(go env GOCACHE)
  • Use per-job cache directories in CI to avoid cross-job corruption
  • Set GOCACHE to a tmpfs mount in Docker for faster I/O
  • Verify build integrity: go vet ./... after build
  • Use go mod verify to check module cache integrity
  • Avoid sharing GOCACHE between concurrent builds without locking