HerokuでGoアプリをデプロイ時に起きる "failed to detect" エラーの対処法

markdown

はじめに (対象読者・この記事でわかること)

この記事は、Go 言語で Web アプリや API を開発し、Heroku へデプロイしようとしているエンジニアを対象としています。
特に「failed to detect」エラーに直面したことがある、あるいは初めて Heroku に Go アプリを置く方に向けて、エラーの根本原因と具体的な対処方法を分かりやすく解説します。

この記事を読むことで、以下のことができるようになります。

Heroku が Go アプリを正しく認識できない原因を特定できる
必要なファイル構成や go.mod、Procfile の書き方を正しく設定できる
実際のエラーメッセージ例とその対処法をステップバイステップで実装できる

執筆のきっかけは、同僚が Heroku デプロイで同様のエラーに何時間も悩んだ経験から、共有できるノウハウとしてまとめたものです。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。

Go 言語の基本的なビルド・実行フロー（go build、go run など）
Git と GitHub（リポジトリのプッシュや Heroku へのリンク）
Heroku CLI のインストールと基本的なコマンド（heroku login、heroku create など）

Heroku で Go アプリをデプロイする際の “failed to detect” エラー概要

Heroku はデプロイ時にアプリケーションの種類を自動判別し、適切なビルドパックを適用します。Go アプリの場合、Heroku は次の条件を満たすと “Go Buildpack” を選択します。

go.mod がプロジェクトルートに存在
Procfile があるか、main パッケージがビルド対象になるか

この二つが揃っていない、あるいはファイル名や場所が期待とずれていると、Heroku はアプリを「検出できない（failed to detect）」と判断し、デプロイが失敗します。エラーメッセージは概ね以下のようになります。

-----> Go app detected
-----> No Go files were found in the repository.
-----> Unable to locate a go.mod file or a .go file at the root.

このエラーは「Go がインストールされていない」ことを示すのではなく、Heroku がビルド対象ファイルを見つけられなかったことを意味します。よくある原因は次の通りです。

原因	具体例
`go.mod` がサブディレクトリにある	`src/go.mod` のようにプロジェクトルートではなく `src/` に配置
`go.mod` が `.gitignore` に入っている	デプロイ時に Git にコミットされず、Heroku に届かない
`Procfile` が存在しない	Web プロセスの宣言がないため、Heroku が実行コマンドを推測できない
ファイル名の大文字小文字ミス	`Go.mod` と大文字で記述すると Linux 系のファイルシステムで認識されない
ビルドパックの手動指定が誤っている	`heroku buildpacks:set heroku/go` で別のパスを指定してしまう

これらを整理した上で、正しいプロジェクト構成に修正すればエラーは解消できます。

ファイル構成のチェックと具体的な解決手順

以下では、典型的な Go プロジェクトを Heroku にデプロイする際の 推奨ディレクトリ構成 と、実際にエラーが出たときの対処フローを示します。

ステップ 1：リポジトリのルートに必須ファイルを配置

go.mod をプロジェクトルートに作成
bash cd your-project go mod init github.com/yourname/your-project これにより、モジュール名と依存関係が go.mod に記録されます。go.mod がサブディレクトリにあると Heroku は検出できません。
Procfile を作成
Heroku は Procfile で実行すべきプロセスを定義します。最もシンプルな例は以下です。
procfile web: bin/your-project ただし、Go の標準ビルドパックは自動的に実行ファイルを bin/ に配置しますので、web: bin/main のように書くのが一般的です。web: プレフィックスは必須です。
.gitignore を確認
go.mod や go.sum が .gitignore に入っていないか確認してください。以下は典型的な除外例です。
gitignore # Binaries /bin/ *.exe *.out # Dependency caches /vendor/

ステップ 2：ローカルでビルドが成功するか確認

Heroku にプッシュする前に、ローカルで次のコマンドを実行し、ビルドが通るか確認します。

Bash

go build -o bin/main .
./bin/main

エラーが出た場合は、go.mod のモジュール名や依存パッケージのバージョンが正しく設定されているかを見直します。go mod tidy を実行すると未使用の依存が削除され、必要なものが自動で取得されます。

ステップ 3：Heroku にデプロイ

Heroku アプリ作成（まだなら）
bash heroku create your-go-app
ビルドパックの確認
Go ビルドパックが自動で設定されますが、念のため明示的に指定しておくと確実です。
bash heroku buildpacks:set heroku/go
リモートリポジトリへプッシュ
bash git add . git commit -m "Add go.mod and Procfile for Heroku deployment" git push heroku main

プッシュ後、Heroku のビルドログに次のような出力が現れれば成功です。

-----> Go app detected
-----> Installing Go 1.22.x
-----> Building /app
-----> Build succeeded!
-----> Launching...

ハマった点やエラー解決

試したこと	結果	学び
`go.mod` を `src/` に置いた	`failed to detect` エラー	ビルドパックはルート直下の `go.mod` のみを認識
`Procfile` の名前を `procfile` にした	同様に検出失敗	ファイル名は大小文字を区別
`heroku buildpacks:set heroku/ruby` と設定したままプッシュ	Ruby ビルドパックが適用され、Go が検出されず	ビルドパックは明示的に設定し直す必要がある
`go.sum` が .gitignore に入っていた	ビルド時にモジュール解決が失敗	`go.mod` と `go.sum` は必ずコミット

解決策まとめ

go.mod と Procfile をリポジトリのルートに配置
ファイル名の大小文字を正しく
.gitignore に重要ファイルが入っていないか確認
ビルドパックが正しいか heroku buildpacks:set heroku/go で保証
ローカルで go build を通す

上記手順を踏めば、failed to detect エラーはほぼ確実に回避できます。

まとめ

本記事では、Heroku で Go アプリをデプロイする際に頻出する 「failed to detect」エラー の原因と、具体的な対策 を解説しました。

必須ファイルはリポジトリルートに配置（go.mod、Procfile）
ファイル名の大小文字や .gitignore の設定に注意
ビルドパックの正しい指定とローカルビルドの検証

これらを実践すれば、Heroku へのデプロイがスムーズに進み、開発サイクルのボトルネックを大幅に削減できます。今後は、Docker コンテナを使ったマルチステージビルドや、Heroku の CI/CD パイプラインといった高度なデプロイ手法についても記事化予定です。

HerokuでGoアプリをデプロイ時に起きる "failed to detect" エラーの対処法🚀