できない.dev

go mod tidy が失敗する(unknown revision / missing go.sum entry)

go mod tidy が unknown revision・missing go.sum entry・410 Gone などで止まる場合、原因はモジュールキャッシュ・GOPROXY・private module の認証のいずれかであることが多い。

公開: 更新:

症状できない · exit 1
go mod tidy
go: downloading github.com/google/uuid v1.6.99
go: example.com/app imports
	github.com/google/uuid: reading github.com/google/uuid/go.mod at revision v1.6.99: unknown revision v1.6.99
解決後できた · exit 0
go build ./...

2026-10-07 に golang:1.23(Go 1.23.12) で実際に打って取った出力。検証環境の詳細

要約

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

実行例

golang:1.23 では、存在しないタグ v1.6.99 を require した go.mod の go mod tidy が unknown revision で終了コード 1 になった。
replace で v1.6.0 へ切り替えると通った。
go.sum が無い状態の go build は、missing go.sum entry で終了コード 1 になった。
go mod download では /go.mod の行しか入らず、go mod tidy まで流すとモジュール本体の h1: 行が入ってビルドが通った。
go 1.30 と書いた go.mod を GOTOOLCHAIN=local で処理すると、go.mod requires go >= 1.30 で止まった。

$ go mod tidy
go: downloading github.com/google/uuid v1.6.99
go: example.com/app imports
	github.com/google/uuid: reading github.com/google/uuid/go.mod at revision v1.6.99: unknown revision v1.6.99
$ echo $?
1
$ go mod tidy
go: downloading github.com/google/uuid v1.6.0
$ cat go.mod
module example.com/app
 
go 1.23
 
require github.com/google/uuid v1.6.99
 
replace github.com/google/uuid v1.6.99 => github.com/google/uuid v1.6.0
$ go build ./...
main.go:6:2: missing go.sum entry for module providing package github.com/google/uuid (imported by example.com/app); to add:
	go get example.com/app
$ echo $?
1
$ go mod download
$ cat go.sum
github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
$ go mod tidy
$ cat go.sum
github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
$ go build ./...
$ echo $?
0
$ GOTOOLCHAIN=local go mod tidy
go: go.mod requires go >= 1.30 (running go 1.23.12; GOTOOLCHAIN=local)
$ go version
go version go1.23.12 linux/amd64

— 2026-10-07 時点の出力

検証環境Python 3.11.2 / Git 2.39.5 / Go 1.23.12 / 2026-10-07 検証
検証日
実行環境
golang:1.23 Debian GNU/Linux 12 (bookworm)
バージョン
  • Python 3.11.2
  • Git 2.39.5
  • Go 1.23.12

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

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 download は、ビルドに使うモジュール本体のチェックサム(末尾が /go.mod でない h1: 行)を go.sum に書かない(Go 1.17 以降。
Go 1.17 のリリースノート(新しいタブで開く))。
download だけで止めると go build は missing go.sum entry のままなので、最後の go mod tidy まで流す(Go 1.23 で確認)。

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

よくある原因

  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 が記録されていない。