7 Error Git Paling Sering Muncul & Cara Mengatasinya (Lengkap)

Git sudah jadi skill wajib untuk programmer modern, tapi pesan error-nya sering bikin bingung — apalagi kalau baru pertama kali ketemu. Kabar baiknya, sebagian besar error Git itu-itu saja polanya. Artikel ini merangkum 7 error Git paling sering muncul lengkap dengan arti pesannya, penyebabnya, perintah perbaikan yang sudah terverifikasi, dan cara mencegahnya terulang.

Untuk setiap error, ikuti pola troubleshooting yang sama: baca pesan error → cek status → perbaiki → cegah. Semua perintah di bawah sudah diverifikasi sintaksnya terhadap dokumentasi resmi Git.

Pola Umum: Cara Membaca Pesan Error Git

Sebelum masuk ke daftar error, pahami dulu anatomi pesan error Git. Hampir semua pesan diawali kata kunci yang menunjukkan tingkat keparahannya: fatal: berarti Git berhenti total dan operasimu dibatalkan, error: berarti satu operasi spesifik gagal, sedangkan baris hint: adalah saran perbaikan langsung dari Git — selalu baca hint-nya, seringkali solusinya sudah tertulis di sana.

Dua perintah adalah sahabat terbaikmu dalam setiap investigasi. git status menunjukkan kondisi repo saat ini — branch aktif, file yang berubah, dan status sinkronisasi dengan remote. Sedangkan git log --oneline -5 menampilkan lima commit terakhir secara ringkas sehingga kamu bisa melihat riwayatnya sekilas. Biasakan menjalankan git status sebelum mengubah apa pun, supaya kamu memperbaiki penyebabnya, bukan gejalanya.

1. failed to push some refs

Pesan error yang muncul:

To github.com:username/repo.git
 ! [rejected]        main -> main (fetch first)
error: failed to push some refs to 'github.com:username/repo.git'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally.

Artinya: branch remote punya commit yang belum ada di repo lokalmu — biasanya karena rekan tim sudah push duluan. Git menolak push-mu supaya riwayat tidak berantakan.

Cara memperbaiki:

# 1. Tarik perubahan remote dan susun ulang commit-mu di atasnya
git pull --rebase origin main

# 2. Jika muncul konflik, selesaikan dulu lalu lanjutkan:
git rebase --continue

# 3. Setelah riwayat rapi, push lagi
git push origin main

Tentang --force: jangan langsung memakai git push --force — ia menimpa remote tanpa ampun. Gunakan versi yang lebih aman:

# Hanya menimpa bila remote tidak berubah sejak terakhir fetch
git push --force-with-lease origin main

⚠️ Peringatan: jangan pernah --force ke branch bersama seperti main tanpa koordinasi tim.

2. Permission denied (publickey)

Pesan error yang muncul:

[email protected]: Permission denied (publickey).
fatal: Could not read from remote repository.

Artinya: Git mencoba terhubung via SSH, tapi server tidak mengenali kunci SSH-mu. Penyebab paling umum: belum membuat SSH key, key belum ditambahkan ke ssh-agent, atau public key belum didaftarkan ke akun GitHub/GitLab-mu.

Cara memperbaiki:

# 1. Cek apakah kamu sudah punya SSH key
ls ~/.ssh

# 2. Tes koneksi ke GitHub
ssh -T [email protected]

# 3. Kalau belum punya key, buat yang baru (ed25519 = standar modern)
ssh-keygen -t ed25519 -C "[email protected]"

# 4. Jalankan ssh-agent dan daftarkan key privatmu
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# 5. Salin PUBLIC key ke GitHub > Settings > SSH and GPG keys
cat ~/.ssh/id_ed25519.pub

3. fatal: not a git repository

Pesan error yang muncul:

fatal: not a git repository (or any of the parent directories): .git

Artinya: kamu menjalankan perintah Git di direktori yang bukan repository Git — salah folder, atau repo-nya memang belum diinisialisasi.

Cara memperbaiki:

# 1. Pastikan kamu di direktori yang benar
pwd
ls -la   # cari folder .git di daftar

# 2a. Kalau salah folder, pindah ke folder proyekmu
cd /path/ke/proyekmu

# 2b. Kalau proyek baru yang belum jadi repo, inisialisasi:
git init

4. src refspec main does not match any

Pesan error yang muncul:

error: src refspec main does not match any
error: failed to push some refs to 'github.com:username/repo.git'

Artinya: Git tidak menemukan branch bernama main. Penyebab klasik: (1) belum ada commit sama sekali, atau (2) nama branch berbeda (misal master).

Cara memperbaiki:

# Lihat nama branch aktif & riwayat commit
git branch
git log --oneline -3

# KASUS A: belum ada commit -> buat commit pertama
git add .
git commit -m "commit pertama"
git push -u origin main

# KASUS B: branch bernama master -> ganti nama ke main
git branch -M main
git push -u origin main

5. Your branch is ahead of 'origin/main'

Pesan yang muncul:

On branch main
Your branch is ahead of 'origin/main' by 2 commits.
  (use "git push" to publish your local commits)

Artinya: ini sebenarnya bukan error — cuma informasi. Kamu punya commit lokal yang belum dikirim ke remote.

Cara memperbaiki:

git push origin main

6. Merge conflict (CONFLICT)

Pesan yang muncul:

Auto-merging app.js
CONFLICT (content): Merge conflict in app.js
Automatic merge failed; fix conflicts and then commit the result.

Artinya: dua pihak mengubah baris yang sama di file yang sama. Ini normal dalam kerja tim.

Cara memperbaiki:

# 1. Lihat file mana saja yang konflik
git status

# 2. Buka file-nya, cari penanda <<<<<<< / ======= / >>>>>>>
#    pilih versi yang benar dan hapus semua baris penanda

# 3. Setelah beres, tandai selesai & commit
git add .
git commit -m "selesaikan konflik merge di app.js"

# JALAN KELUAR DARURAT (sebelum commit hasil merge):
git merge --abort

7. refusing to merge unrelated histories

Pesan error yang muncul:

fatal: refusing to merge unrelated histories

Artinya: kamu mencoba menggabungkan dua riwayat yang tidak punya commit nenek moyang yang sama.

Cara memperbaiki:

# Izinkan penggabungan riwayat yang tidak berhubungan (sekali ini saja)
git pull origin main --allow-unrelated-histories

⚠️ Peringatan: hanya pakai untuk kasus spesifik ini. Jangan jadikan kebiasaan.

Tabel Ringkas: Gejala → Perintah Pertama

Gejala	Perintah pertama yang dijalankan
failed to push some refs	git pull --rebase origin main lalu push lagi
Permission denied (publickey)	ssh -T [email protected], lalu setup SSH key
fatal: not a git repository	pwd + ls -la, pindah folder atau git init
src refspec main does not match any	git branch — cek nama branch
Your branch is ahead of...	git push origin main (bukan error!)
Merge conflict	git status, edit penanda, commit
refusing to merge unrelated histories	git pull origin main --allow-unrelated-histories

Kesimpulan

Tujuh error di atas mencakup sebagian besar masalah Git yang ditemui sehari-hari. Kuncinya: baca pesan error kata per kata (terutama baris hint:), cek kondisi dengan git status sebelum mengubah apa pun, dan jangan panik — hampir semua error Git bisa dibatalkan atau diperbaiki.

Kalau kamu baru belajar Git, simpan tabel ringkas di atas sebagai contekan. Dan ingat aturan emasnya: commit kecil, push rutin, jangan pernah --force ke branch orang lain.