go mod tidy が失敗する（unknown revision / missing go.sum entry）

要約

go mod tidy が止まるのは大別して 3 系統。ネットワーク / GOPROXY 系、キャッシュ系、バージョン / タグ系。
エラーメッセージから判別し、GOPRIVATE 設定や go clean -modcache で順に潰す。

よくある原因

1. private module: 社内 GitHub Enterprise / GitLab を proxy.golang.org 経由で取りに行って失敗。
2. キャッシュ破損: $GOPATH/pkg/mod 配下に書き込み権限が無い、または部分的に壊れている。
3. Go バージョン不一致: go.mod で go 1.22 指定なのにローカル Go が 1.20。
4. 削除タグ: 依存ライブラリが force-push でタグを消した、またはリネームしたケース。
5. go.sum 不整合: 新規依存の checksum が記録されていない。

解決策

1. private module を GOPROXY 対象外にする

go env -w GOPRIVATE="github.com/myorg/*,gitlab.example.com/*"

GOPRIVATE に列挙したパターンは direct（Git でクローン）で取得され、checksum DB にも問い合わせない。
詳細は Go Modules Reference を参照。

2. キャッシュをクリアして再取得

go clean -modcache
go mod download
go mod tidy

容量が大きいと数 GB 消えるので注意。

3. Go バージョンを更新する

go version
# go.mod の指定より低ければ更新

4. 削除されたタグを replace で迂回

// go.mod
require example.com/lib v1.2.3
replace example.com/lib v1.2.3 => example.com/lib v1.2.2

5. go.sum を再生成する

rm go.sum
go mod download
go mod tidy

エラーを無視して埋めるなら go mod tidy -e を使う。