エラーの内容
go build、go run、または go get を実行すると、以下のエラーが発生します：
go: module not found
より詳細なコンテキストが表示される場合もあります：
go: github.com/some/package@v1.2.3: reading https://proxy.golang.org/github.com/some/package/@v/v1.2.3.info: 404 Not Found
go: module not found
Go がモジュールを見つけられない状態です — ローカルキャッシュにも、プロキシにも存在しないか、go.mod の設定が間違っています。原因は主に7つのいずれかです。
原因
原因はさまざまで、意外と多岐にわたります：
- プロジェクトルートに
go.modが存在しない、またはモジュールディレクトリの外で Go コマンドを実行している go.modのモジュールパスが、コードで実際にインポートしているパスと一致していない- 指定したパッケージバージョンが存在しない — タグがプッシュされていないか、削除されている
GO111MODULE=offが設定されているため、Go がgo.modを完全に無視して GOPATH モードにフォールバックしている- 公開プロキシ
proxy.golang.orgからアクセスできないプライベートモジュール - 存在しないローカルパスを指している
replaceディレクティブ - 破損または不完全なモジュールキャッシュ
解決方法
1. Go モジュール内にいることを確認する
プロジェクトルートに go.mod が存在するか確認します：
ls go.mod
ファイルがない場合は初期化します：
go mod init github.com/yourname/yourproject
次に、必要な依存関係をすべて取得します：
go mod tidy
2. モジュールパスがインポートと一致しているか確認する
go.mod を開いて最初の行を確認します：
module github.com/yourname/yourproject
go 1.21
よくある落とし穴：コードが github.com/yourname/yourproject/utils をインポートしているのに、go.mod でモジュールが myapp と宣言されている場合があります。Go は2つの異なるモジュールパスと見なして失敗します。インポート文で使用しているパスと完全に一致するよう module 行を修正してください。
3. GO111MODULE を確認する
モジュールモードは Go 1.16 以降デフォルトになっています。ただし、古い CI マシンなどで誰かが環境変数に GO111MODULE=off を設定していると、Go は go.mod を黙って無視します。
go env GO111MODULE
off になっている場合は修正します：
# Linux/macOS
export GO111MODULE=on
# Windows (PowerShell)
$env:GO111MODULE = "on"
またはデフォルトに戻すためにクリアします：
go env -w GO111MODULE=
4. 不足しているモジュールを直接取得する
特定のパッケージが見つからない場合は、明示的に追加します：
go get github.com/some/package@latest
特定のリリースに固定する場合：
go get github.com/some/package@v1.2.3
go.mod と go.sum の整合性を保つため、必ず後で go mod tidy を実行してください：
go mod tidy
5. 壊れた replace ディレクティブを確認する
存在しないローカルパスを指している go.mod の replace ブロックは、毎回このエラーを引き起こします：
replace github.com/some/package => ../local-fork
ls ../local-fork を実行してディレクトリが存在するか確認します。パスが変わっている場合は更新し、オーバーライドが不要になった場合はディレクティブを削除してください。
6. プライベートモジュールに対応する
公開プロキシはプライベートリポジトリ — GitHub Enterprise、GitLab セルフホスト、Gitea など — にアクセスできません。プライベートドメインにはプロキシをスキップするよう Go に指示します：
go env -w GOPRIVATE=gitlab.company.com/*
go env -w GONOSUMCHECK=gitlab.company.com/*
これにより、Go はそれらのモジュールを proxy.golang.org 経由ではなく、ソースから直接取得します。認証には SSH キーまたは ~/.netrc エントリも必要です。
7. モジュールキャッシュを消去する
ダウンロードの途中でキャッシュが破損し、以降の取得がブロックされることがあります。キャッシュをクリアします：
go clean -modcache
go mod download
大きなプロジェクトでは数百メガバイトの再ダウンロードが発生する場合がありますが、キャッシュの問題を切り分ける最も確実な方法です。
修正の確認
すべてのモジュールが正常に解決されることを確認します：
go mod verify
期待される出力：
all modules verified
次にフルビルドを実行します：
go build ./...
クリーンな出力が得られれば完了です。特定の依存関係がどこから来ているか確認するには：
go mod graph | grep some/package
クイック診断チェックリスト
- go.mod がない？ →
go mod initを実行する - モジュールパスが一致しない？ → go.mod の
module行を修正する - GO111MODULE=off になっている？ → 解除するか
onに設定する - バージョンが存在しない？ → リポジトリのタグを確認し、
@latestを使用する - プライベートリポジトリ？ → ドメインに
GOPRIVATEを設定する - replace ディレクティブが壊れている？ → パスを確認するかディレクティブを削除する
- キャッシュが古い？ →
go clean -modcacheを実行する
リポジトリをクローンしたばかりの場合
プロジェクトをクローンしてすぐにこのエラーが発生した場合は、ビルドの前に go mod download を実行してください。go.sum に記載されているすべての依存関係をローカルキャッシュに取得します — Go における npm install に相当する操作です。
git clone https://github.com/example/repo
cd repo
go mod download
go build ./...
クローン直後の「module not found」エラーのほとんどは、このひとつの手順で解消されます。