こんにちは、かつコーチです。
ここまでGitHub編として、アカウント作成からPull Request、ブランチ運用、CI/CDまで解説してきました。
ただ、実際に手を動かしていると、記事を読んだだけでは気づけない小さなエラーに何度もぶつかるものです。
この記事では、私自身がつまずいた経験も含め、初心者がよく遭遇するGitHubのエラーと対処法を1つの記事にまとめました。
この記事の役割：迷子になりやすい交差点の案内図
つまずきポイントまとめ＝交差点の案内図
この記事は、GitHubというまちの中でも特に迷いやすい「交差点」を集めた案内図のようなものだと考えてください。
初めて訪れるまちでは、どの道でも道に迷う可能性がありますが、実際には「多くの人が同じ場所で同じように迷っている」交差点がいくつか存在します。
案内図があれば、その交差点に差し掛かったときに「ああ、ここはみんな迷うところだ」と落ち着いて対処できます。
なぜエラーを一覧で知っておくと役立つのか
エラーメッセージは、初めて見たときは何を意味しているのか分からず、不安になりがちです。
しかし多くのエラーは原因のパターンが決まっており、事前に知っておくだけで焦らず対処できるようになります。
この記事では、特に初心者がよくぶつかる4つの交差点を、実際のエラーメッセージとともに紹介します。
よくあるつまずきポイント・エラー対処
交差点1：Permission denied (publickey)でpushできない
SSH接続でリモートリポジトリにpushしようとした際、以下のようなエラーで止まってしまうケースです。
❌ Before：SSH鍵をGitHubに登録していない、または鍵の指定を誤っている
$ git push origin main
git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.
このエラーは、あなたの合鍵（SSH鍵）が、GitHub側の鍵穴の登録リストに載っていないという意味です。
✅ After：SSH接続をテストし、鍵の登録状況を確認する
$ ssh -T git@github.com
Hi katsu-coach! You've successfully authenticated, but GitHub does not provide shell access.
このメッセージが出れば認証は成功しています。
失敗する場合は、~/.ssh/id_ed25519.pubの内容がGitHubのSettings > SSH and GPG keysに登録されているか、ssh-add -lで鍵がエージェントに読み込まれているかを確認してください。
交差点2：rejected（non-fast-forward）でpushが弾かれる
チーム開発で複数人が同じブランチにpushしていると、以下のエラーに遭遇します。
❌ Before：自分のローカルが最新のリモートより古い状態でpushする
$ git push origin main
! [rejected] main -> main (fetch first)
error: failed to push some refs to 'github.com:your-org/your-repo.git'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally.
これは、自分が知らない間に誰かがリモートに新しい変更をpushしていて、その上に自分の変更を無理やり上書きしようとしていることをGitが止めてくれているサインです。
✅ After：pull（fetch + merge）してから改めてpushする
$ git pull origin main
$ git push origin main
交差点で、先に交差点へ入っていた車がいるのに気づかず突っ込もうとした状態を、信号（Git）が赤で止めてくれたとイメージすると分かりやすいです。
コンフリクトが発生した場合は、「Pull Requestでのコンフリクト解消の流れ」で解説した手順で解消してください。
交差点3：detached HEAD state で身動きが取れなくなる
特定のコミットをgit checkoutした際に、以下のようなメッセージが表示されて戸惑うケースです。
❌ Before：意味を理解せず、そのまま作業を進めてしまう
$ git checkout a1b2c3d
Note: switching to 'a1b2c3d'.
You are in 'detached HEAD' state...
私が初めてこのメッセージを見たときは意味が分からず、そのままファイルを編集してコミットしてしまい、後で「このコミットがどのブランチにも属していない」ことに気づいて焦った経験があります。
この状態は、案内図に載っていない脇道に一時的に入り込んでいて、どの本線ともつながっていない状態です。
脇道での作業内容は、ブランチを作らずに別の場所へ移動すると、迷子のまま見失ってしまう可能性があります。
✅ After：作業を残したい場合は、その場でブランチを作成する
$ git checkout -b fix/temp-investigation
detached HEADの状態で何かコミットしてしまった場合でも、このコマンドでその場からブランチを生やせば、変更履歴を本線とつながった安全な道に戻せます。
過去のコミットを一時的に確認したいだけなら、変更を加えずにgit checkout mainで本線に戻れば問題ありません。
交差点4：.gitignoreに書いたのにファイルが追跡され続ける
.gitignoreに除外設定を書いたのに、なぜかそのファイルがgit statusに表示され続けるケースです。
❌ Before：すでにGit管理下にあるファイルを後から.gitignoreに追加する
$ echo "node_modules/" >> .gitignore
$ git status
modified: node_modules/some-package/index.js
.gitignoreは、まだ一度もコミットされていない未追跡のファイルにしか効きません。
すでに案内図に「立入禁止」と書き足しても、すでに敷地内に入ってしまっている車には効果がないのと同じです。
✅ After：追跡をキャッシュから外してから.gitignoreを効かせる
$ git rm -r --cached node_modules
$ git commit -m "stop tracking node_modules"
--cachedオプションは、実際のファイルは手元に残したまま、Gitの管理対象からだけ外すという意味です。
この手順を踏んで初めて、以降.gitignoreの設定が正しく機能するようになります。
応用・一歩先の使い方
エラーメッセージは最後まで読む習慣をつける
Gitのエラーメッセージには、多くの場合hint:という形で対処のヒントが一緒に表示されます。
エラーの1行目だけを見て検索するのではなく、ヒントまで含めて読む習慣をつけると、この記事に載っていない新しいエラーにも自力で対処しやすくなります。
迷ったらgit statusとgit log --onelineでまず現在地を確認する
トラブルに遭遇したときほど、焦って次のコマンドを打ちたくなりますが、まずはgit statusで今どんな状態か、git log --onelineでどこまでの履歴があるかを確認するのが鉄則です。
案内図と同じで、まず「自分が今どの交差点にいるのか」を把握することが、正しい道への一番の近道です。
まとめ
この記事のポイント
- Permission deniedはSSH鍵の登録漏れ、rejectedはリモートとの差分が原因であることが多い
- detached HEADで作業を残したいときは、その場で
git checkout -bしてブランチ化する .gitignoreは未追跡ファイルにしか効かないため、既存ファイルはgit rm --cachedで追跡を外す- 迷ったら
git statusで現在地を確認する習慣が、トラブル対処の一番の近道になる
次に読むべき記事
GitHub編の締めくくりとして、次は「GitHubとGitLab、チーム開発でどちらを選ぶべきか比較検証」で、他の選択肢との違いも押さえておきましょう。