Go "failed to initialize build cache" - Fix Cache Permissions in CI

By Kaveh Alemi·Latchkey

Go needs a writable build cache directory (GOCACHE). When that path is owned by another user or mounted read-only - common after a cache restore or a UID change between container layers - Go cannot initialize it and fails.

What this error means

A build fails with failed to initialize build cache at <path>: ... permission denied, or mkdir <path>: permission denied. It often appears after switching users in a container or restoring a cache owned by root.

go output

go: failed to initialize build cache at /home/runner/.cache/go-build:
	mkdir /home/runner/.cache/go-build: permission denied

Common causes

GOCACHE owned by a different user

A cache directory created as root (or restored with root ownership) is not writable by the non-root user the build runs as.

A read-only or missing cache path

GOCACHE points at a path that is mounted read-only or does not exist and cannot be created by the current user.

How to fix it

Point GOCACHE at a writable directory

Set the cache to a path the build user owns.

Terminal

export GOCACHE="$HOME/.cache/go-build"
mkdir -p "$GOCACHE"
go build ./...

Fix ownership of a restored cache

When a cached directory comes back owned by root, reassign it to the build user.

Terminal

chown -R "$(id -u):$(id -g)" "$HOME/.cache/go-build"

Cache the right path for the build user

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: ~/.cache/go-build
    key: go-build-${{ hashFiles('go.sum') }}

How to prevent it

Set GOCACHE to a directory the build user owns.
Normalize cache ownership after restoring it across user contexts.
Avoid running part of the build as root and part as a non-root user.

Frequently asked questions

What causes "build cache permission denied"?