Common Git Errors

Quick Summary

Git error messages can be cryptic. This page catalogs the most frequently encountered errors, explains why they happen, and provides copy-paste fixes.

---

Error Reference

fatal: not a git repository

Meaning: You're running a Git command outside a Git repository.

# Fix: Initialize a repo or navigate to one
git init            # Create a new repo here
cd /path/to/repo    # Navigate to your repo

---

error: failed to push some refs

Meaning: The remote has commits your local branch doesn't have.

# Fix: Pull and integrate remote changes first
git pull --rebase origin main
git push

---

CONFLICT (content): Merge conflict in <file>

Meaning: Two branches modified the same lines.

# Fix: Resolve manually
# 1. Open the file, find <<<<<<< markers
# 2. Edit to desired result, remove markers
# 3. Stage and commit
git add <file>
git commit

---

Permission denied (publickey)

Meaning: SSH key not found or not accepted by GitHub.

# Fix: Check SSH setup
ssh-add -l                         # List loaded keys
ssh -vT git@github.com             # Verbose test
cat ~/.ssh/config                  # Check SSH config

See SSH Setup for full details.

---

fatal: refusing to merge unrelated histories

Meaning: Trying to merge repositories with no common ancestor.

# Fix: Allow the merge (if intentional)
git pull origin main --allow-unrelated-histories

---

error: Your local changes would be overwritten by checkout

Meaning: You have uncommitted changes that conflict with the target branch.

# Fix options:
git stash                    # Save changes temporarily
git checkout <branch>
git stash pop                # Restore changes

# Or commit first
git add . && git commit -m "Save WIP"
git checkout <branch>

---

detached HEAD

Meaning: You checked out a commit hash instead of a branch.

# Fix: Create a branch from current position
git switch -c save-my-work

# Or return to a branch
git switch main

---

fatal: remote origin already exists

Meaning: You're trying to add a remote named origin that already exists.

# Fix: Update the existing URL
git remote set-url origin <new-url>

# Or remove and re-add
git remote remove origin
git remote add origin <new-url>

---

error: src refspec main does not match any

Meaning: Branch main doesn't exist (no commits yet, or different branch name).

# Fix: Check branch name
git branch                   # See current branches

# Create initial commit if needed
git add . && git commit -m "Initial commit"
git push -u origin main

---

fatal: unable to access... Could not resolve host

Meaning: Network issue — can't reach GitHub.

# Fix: Check connectivity
ping github.com
# Check proxy/firewall settings
git config --global http.proxy    # View proxy

---

Error Decision Table

Error Pattern	Likely Cause	Quick Fix
not a git repository	Wrong directory	cd to repo or git init
failed to push	Remote is ahead	git pull --rebase && git push
CONFLICT	Same lines edited	Resolve manually + git add
Permission denied	SSH key issue	Check ~/.ssh/config
unrelated histories	Different repos	--allow-unrelated-histories
detached HEAD	Checked out a hash	git switch -c <branch>
already exists	Duplicate remote	git remote set-url
does not match any	No commits/wrong name	git branch to verify

---

Best Practices

• Read the full error message — Git often suggests the fix
• Use git status before running risky commands
• Know git reflog — your safety net for recovering from mistakes
• Don't panic on conflicts — git merge --abort resets everything

What's Next

1. Undoing Changes — Undo commits, staged changes, and merges
2. Recovery Techniques — Recover deleted branches and lost commits