Goのバージョンアップ運用を TOOLCHAIN 方式（go.modやGOTOOLCHAINによる管理）に変更してからテストコードを実行したところ、以下のエラーが発生するようになりました。
$ go: overlay contains a replacement for /Users/hoge/go/pkg/mod/golang.org/toolchain@v0.0.1-go1.25.4.darwin-arm64/src/time/time.go. Files beneath GOMODCACHE (/Users/hoge/go/pkg/mod) must not be replaced.
GoのIssueを確認したところ、 -overlay オプションが機能してないのではと考えていました。
しかし、実際には、Go1.21以降の自動アップデートとの競合による問題で、キャッシュが残っていたのが原因でした。
-overlay オプションによるエラーとなった時の整理しておきたいポイントをまとめます。
環境情報
端末: Macbook Air
Go Version: 1.25.4
＊ローカルは、homebrewにてインストールして管理していました。
＊今回は、2025年12月3日 Go v1.25.5 がリリースされたので、対応したタイミングで、 Go v1.25.5 となりました。
確認事項① ローカル環境のGoのバージョン
ローカル環境のGoのバージョンと TOOLCHAIN（go.mod）でのGoのバージョンに差分がある場合は、エラーとなる可能性があります。
例えば、go.modに記載されているバージョンが、 v1.25.4 で、ローカル環境が v1.24 となっているとします。
この場合、go.modに記載されているバージョンを使おうとするため、意図的に、高いGoのバージョンを使おうとします。
結果として、差分のインストールが行われますが、自動アップデートで入った場合は置き換え禁止のルールに該当します。
結果として、-overlay オプションのエラーが発生します。
-overlay オプションエラーに遭遇した時、go.mod/TOOLCHAIN、そして、ローカル環境のバージョンに差分が発生していないかを確認して、必要に応じて、ローカル環境のGoのバージョンをあげることで解消されます。
確認事項② homebrewのキャッシュ
キャッシュ情報は、以下に配置されています。
$ /Users/hoge/go/pkg/mod
全てのダウンロード済みモジュール（toolchainを含む）が配置されており、 ls -la コマンドを叩くことで、パッケージを確認できます。
このまま、 go clean -modcache を実行すれば、キャッシュは削除されます。
しかしながら、一部のモジュールは、modディレクトリ以下に存在せず、mod ディレクトリと同じ階層に存在するケースがあります。
$ ls -la /Users/hoge/go/pkg/
$ staff 544 12 8 10:31 mod
$ staff 96 3 7 2025 sumdb
$ staff 320 11 21 14:12 testtime
今回は、homebrewで管理しているGoを一度削除して、再度インストールすることで、mod ディレクトリと同じ階層に存在するモジュールが更新されました。
Goのアンインストール
$ brew uninstall go
Goの再インストール
$ brew install go
$ go version
$ go version go1.25.5 darwin/arm64
再インストール実施前:
staff 320 11 21 14:12 testtime
再インストール実施後:
staff 384 12 8 13:56 testtime ← 更新されている
homebrewにて管理している場合は、削除→再インストールによるGoのバージョンアップで解消されました。
Goのバージョンを最新にて管理する
Go1.25 にて導入された -overlay オプションの制約によって、 GOMODCACHE 以下は置き換え禁止となっています。
そのため、Goのバージョン違いによって、自動インストール→置き換え→エラーという流れが生まれてしまいます。
TOOLCHAIN にて、Goのバージョンを管理されている場合は、ローカルのGoのバージョンを見直して、最新にしておくことをおすすめします。