Common Git Errors and Fixes
Every developer hits the same wall of Git error messages sooner or later. The good news is that almost every common error has a clear, repeatable fix. This page documents the 15 most common Git errors you will encounter, with the exact terminal output, the root cause, and the fastest path to resolution.
Error message | Root cause | Quick fix |
|---|---|---|
Your local changes would be overwritten by merge | You have uncommitted changes that conflict with incoming changes | git stash, then git pull, then git stash pop |
fatal: not a git repository | Current directory is not inside a Git repo | Run git init or cd to the correct directory |
error: failed to push some refs to ... | Remote has commits your local branch does not have | git pull --rebase origin main, then push |
CONFLICT (content): Merge conflict in ... | Two branches edited the same lines differently | Open the file, edit conflict markers, git add, git commit |
HEAD detached at abc1234 | You checked out a commit hash or tag directly | git switch -c new-branch-name to save work |
fatal: refusing to merge unrelated histories | The two repos share no common ancestor commit | git pull origin main --allow-unrelated-histories |
error: pathspec 'my file' did not match any file(s) known to git | Path contains spaces and was not quoted | Quote the path: git add "my file.txt" |
Permission denied (publickey) | SSH key is not added to the SSH agent or to GitHub/GitLab | ssh-add ~/.ssh/id_ed25519 and add public key to hosting platform |
error: Your local changes to the following files would be overwritten by checkout | Switching branches while you have uncommitted edits to tracked files | git stash before switching, or commit your changes first |
fatal: pathspec did not match any file(s) | Typo in filename or file not yet staged | Check git status for exact filenames; git add the file first |
Updates were rejected because the tip of your current branch is behind | Someone else pushed while you were working | git fetch && git rebase origin/main, then push again |
error: cannot pull with rebase: You have unstaged changes | git pull --rebase requires a clean working tree | git stash, then git pull --rebase, then git stash pop |
fatal: remote origin already exists | Tried to add a remote named "origin" when one already exists | git remote set-url origin |
nothing to commit, working tree clean | You ran git commit with no staged changes | git add |
error: The following untracked working tree files would be overwritten | A new file in your working tree would be replaced by a file from the incoming branch | Back up or delete the untracked file, then retry the operation |
1. Your local changes would be overwritten by merge
Error output
git pull # error: Your local changes to the following files would be overwritten by merge: # src/config.js # Please commit your changes or stash them before you merge. # Aborting
Git refuses to overwrite your uncommitted edits. The fix is to temporarily save your work with git stash, pull, and then restore your stash.
Fix
git stash # save uncommitted changes git pull # pull the remote commits git stash pop # restore your saved changes # If there are conflicts after stash pop, resolve them normally
2. fatal: not a git repository
Error output
git status # fatal: not a git repository (or any of the parent directories): .git
You are running a Git command outside of a Git repository. Either you need to initialise one, or you are in the wrong directory.
Fix
# Option A: initialise a new repository here git init # Option B: navigate to the right directory cd /path/to/your/project git status # Option C: clone an existing repo git clone https://github.com/user/repo.git
3. error: failed to push some refs
Error output
git push origin main # To https://github.com/user/repo.git # ! [rejected] main -> main (fetch first) # error: failed to push some refs to 'https://github.com/user/repo.git' # hint: Updates were rejected because the remote contains work that you do # hint: not have locally. Integrate the remote changes (e.g. # hint: 'git pull ...') before pushing again.
Someone else pushed to the remote while you were working. You must integrate their commits before Git will accept yours.
Fix with rebase (cleaner history)
git pull --rebase origin main # Rebases your local commits on top of the remote commits git push origin main # Now succeeds
Fix with merge (preserves merge commit)
git pull origin main git push origin main
4. CONFLICT (content): Merge conflict in...
Error output
git merge feature-login # Auto-merging src/auth.js # CONFLICT (content): Merge conflict in src/auth.js # Automatic merge failed; fix conflicts and then commit the result.
This is not really an error — it is Git asking for human judgement. Open the conflicted file, look for the <<<<<<< / ======= / >>>>>>> markers, edit the file to the desired final state, remove the markers, and continue.
Resolution workflow
# 1. See which files conflict git status # 2. Open each conflicted file and resolve (editor or merge tool) git mergetool # optional: opens a visual tool # 3. Mark each file as resolved git add src/auth.js # 4. Finish the merge git commit
5. HEAD detached at...
Warning output
git checkout abc1234 # Note: switching to 'abc1234'. # # You are in 'detached HEAD' state. You can look around, make experimental # changes and commit them, and you can discard any commits you make in this # state without impacting any branches by switching back to a branch. # # HEAD is now at abc1234 Add login form
A detached HEAD means you are not on any branch. Commits you make here will be orphaned when you switch away. If you want to keep work done in this state, create a branch immediately.
Fix: save your work to a new branch
git switch -c my-experiment # HEAD is now pointing at a branch — your commits are safe # Or, if you just want to go back without saving: git switch main
6. fatal: refusing to merge unrelated histories
Error output
git pull origin main # fatal: refusing to merge unrelated histories
This happens when you git init locally and separately create a repo on GitHub with a README, then try to pull. The two repositories have no common ancestor, so Git refuses the merge by default.
Fix
git pull origin main --allow-unrelated-histories # Git creates a merge commit joining the two histories # Then push normally git push origin main
7. error: pathspec did not match any file(s) known to git
Error output
git add my documents/notes.txt # fatal: pathspec 'documents/notes.txt' did not match any files
Paths with spaces must be quoted. Without quotes, the shell splits the path into multiple arguments.
Fix
git add "my documents/notes.txt" # Or escape the space: git add my documents/notes.txt
8. Permission denied (publickey)
Error output
git push origin main # git@github.com: Permission denied (publickey). # fatal: Could not read from remote repository. # # Please make sure you have the correct access rights # and the repository exists.
SSH authentication failed. Either your SSH key is not loaded into the SSH agent, or your public key has not been added to your GitHub / GitLab account.
Fix
# 1. Check if your key is loaded ssh-add -l # If empty: "The agent has no identities" # 2. Add your key to the agent ssh-add ~/.ssh/id_ed25519 # 3. Test the connection ssh -T git@github.com # Hi username! You've successfully authenticated... # 4. If you have no SSH key, generate one ssh-keygen -t ed25519 -C "you@example.com" # Then copy the public key to GitHub: Settings → SSH Keys cat ~/.ssh/id_ed25519.pub
9. error: Your local changes would be overwritten by checkout
Error output
git switch feature-x # error: Your local changes to the following files would be overwritten by checkout: # src/index.js # Please commit your changes or stash them before you switch branches. # Aborting
Fix
# Option A: stash and switch git stash git switch feature-x git stash pop # Option B: commit your changes first git add -A git commit -m "WIP: save progress" git switch feature-x # Option C: discard local changes (Warning: irreversible) git restore src/index.js git switch feature-x
10. Updates were rejected because the tip of your current branch is behind
Error output
git push # To https://github.com/user/repo.git # ! [rejected] main -> main (non-fast-forward) # error: failed to push some refs to 'https://github.com/user/repo.git' # hint: Updates were rejected because the tip of your current branch is behind # hint: its remote counterpart.
Fix
git fetch origin git rebase origin/main git push origin main
11. error: cannot pull with rebase: You have unstaged changes
Error output
git pull --rebase # error: cannot pull with rebase: You have unstaged changes. # Please commit or stash them.
Fix
git stash git pull --rebase git stash pop
12. fatal: remote origin already exists
Error output
git remote add origin https://github.com/user/repo.git # fatal: remote origin already exists.
Fix
# Check the current remote URL git remote -v # Update the URL instead of adding git remote set-url origin https://github.com/user/new-repo.git # Or remove and re-add git remote remove origin git remote add origin https://github.com/user/repo.git
13. nothing to commit, working tree clean
Output
git commit -m "my changes" # On branch main # nothing to commit, working tree clean
This is not an error — Git is telling you there is nothing staged. You need to stage your changes before committing.
Fix
# See what is in your working tree git status # Stage specific files git add src/app.js # Stage all changes git add -A # Now commit git commit -m "my changes"
14. The following untracked working tree files would be overwritten
Error output
git checkout feature-x # error: The following untracked working tree files would be overwritten by checkout: # config/local.json # Please move or remove them before you switch branches. # Aborting
Fix
# Option A: back up and remove the file cp config/local.json ~/Desktop/local.json.bak rm config/local.json git switch feature-x # Option B: if you want to keep it tracked, add it first git add config/local.json git commit -m "add local config" git switch feature-x
15. SSL certificate problem / unable to get local issuer certificate
Error output
git clone https://internal.company.com/repo.git # fatal: unable to access 'https://internal.company.com/repo.git/': # SSL certificate problem: unable to get local issuer certificate
Common on corporate networks with a custom certificate authority. The proper fix is to add the corporate CA certificate to your system trust store, not to disable SSL.
Fix
# Proper fix: tell Git where the CA bundle is git config --global http.sslCAInfo /path/to/corporate-ca.crt # For a single repo only git config http.sslCAInfo /path/to/corporate-ca.crt
General debugging workflow
Read the full error message — Git is usually explicit about what went wrong.
Run
git status— it almost always tells you what state you are in and what commands are available.Run
git log --oneline -5to understand the recent commit history.Use
git reflogto recover from mistakes — it records every HEAD movement.Check
git remote -vwhen push/pull issues are mysterious — you might be pointing at the wrong URL.