The Go programming language relies on a build cache to optimize compilation times by reusing previously built packages. When the Go compiler or related tools attempt to access this cache but cannot locate a suitable directory, you may encounter the following error:
build cache is required, but could not be located: GOCACHE is not defined and neither $XDG_CACHE_HOME nor $HOME are defined
This comprehensive guide provides detailed steps to understand and resolve this issue, ensuring a smooth development experience with Go.
The error indicates that Go cannot determine where to store its build cache because key environment variables are undefined. The build cache is essential for speeding up builds by avoiding redundant compilation of unchanged code. Go searches for the cache directory in the following order:
If all three environment variables are unset, Go cannot determine where to place the build cache, resulting in the error message.
HOME
directory may not be properly defined for the executing user.Depending on your operating system, the method to set environment variables varies.
Add the following lines to your shell configuration file (e.g., .bashrc
, .zshrc
):
export GOCACHE="$HOME/.cache/go-build"
export XDG_CACHE_HOME="$HOME/.cache"
export HOME="/path/to/your/home/directory"
After adding, reload the configuration:
source ~/.bashrc # or source ~/.zshrc
Set environment variables using Command Prompt or PowerShell.
Using Command Prompt:
setx GOCACHE "C:\Users\YourUsername\.cache\go-build"
setx XDG_CACHE_HOME "C:\Users\YourUsername\.cache"
setx HOME "C:\Users\YourUsername"
Using PowerShell:
[Environment]::SetEnvironmentVariable("GOCACHE", "C:\Users\YourUsername\.cache\go-build", "User")
[Environment]::SetEnvironmentVariable("XDG_CACHE_HOME", "C:\Users\YourUsername\.cache", "User")
[Environment]::SetEnvironmentVariable("HOME", "C:\Users\YourUsername", "User")
After setting, restart your Command Prompt, PowerShell, or IDE to apply changes.
Ensure that the directories specified by the environment variables exist and are writable.
For Unix/Linux/macOS:
mkdir -p "$GOCACHE"
chmod -R 700 "$GOCACHE"
For Windows:
New-Item -ItemType Directory -Path "C:\Users\YourUsername\.cache\go-build" -Force
Alternatively, use File Explorer to create the directories manually.
Confirm that the environment variables are correctly set.
Using go env
:
go env
Look for the GOCACHE
variable in the output.
Directly Checking Variables:
Unix/Linux/macOS:
echo $GOCACHE
echo $XDG_CACHE_HOME
echo $HOME
Windows (Command Prompt):
echo %GOCACHE%
echo %XDG_CACHE_HOME%
echo %HOME%
Windows (PowerShell):
echo $env:GOCACHE
echo $env:XDG_CACHE_HOME
echo $env:HOME
Verify that the user has read and write permissions to the cache directories.
For Unix/Linux/macOS:
ls -ld "$GOCACHE"
chmod -R u+rw "$GOCACHE"
For Windows:
Right-click the cache directory, navigate to Properties > Security, and ensure the user has appropriate permissions.
Integrated Development Environments (IDEs) may not inherit environment variables by default. Configure your IDE to recognize the necessary variables.
IntelliJ IDEA:
open -a "IntelliJ IDEA"
GOCACHE
with the desired path.VS Code:
CodeRunner:
Set GOCACHE
and HOME
in the app settings. Refer to discussions such as this Reddit thread for additional context.
In containerized environments, explicitly set environment variables within the Dockerfile.
ENV GOCACHE=/tmp/gocache
ENV HOME=/root
Ensure that the specified directories exist and are writable within the container.
In CI/CD configurations, define the necessary environment variables to ensure Go can locate the build cache.
env:
GOCACHE: /tmp/go-build-cache
HOME: /home/runner
Example snippet for a GitHub Actions workflow:
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v3
- name: Set Environment
run: |
mkdir -p /tmp/go-build-cache
export GOCACHE=/tmp/go-build-cache
export HOME=/home/runner
- name: Install Go
uses: actions/setup-go@v3
with:
go-version: '1.20'
- name: Build Application
run: go build ./...
If the error persists after following the above steps, perform the following debugging actions:
GOCACHE
, XDG_CACHE_HOME
, and HOME
are correctly set.GOCACHE
, Go defaults to:
$HOME/.cache/go-build
%LocalAppData%\go-build
GOCACHE
Explicitly: Especially in containerized or automated environments to ensure consistency.After applying the fixes, verify that Go recognizes the build cache location:
go env GOCACHE
The output should display the path to the cache directory you set.
The Go build cache is a pivotal component for efficient compilation. Encountering the error message regarding undefined GOCACHE
, XDG_CACHE_HOME
, and HOME
variables signifies that Go cannot locate a suitable directory for caching build artifacts. By systematically setting the necessary environment variables, ensuring proper directory permissions, and configuring your development environment appropriately, you can resolve this issue and optimize your Go development workflow.