GitCommon Git Errors

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 to change the URL

nothing to commit, working tree clean

You ran git commit with no staged changes

git add before git commit

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

Bash
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

Bash
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
Tip
If the stash pop causes a conflict, run `git stash show -p` to inspect what was stashed, then resolve the conflict as you would a merge conflict.
2. fatal: not a git repository

Error output

Bash
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

Bash
# 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

Bash
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)

Bash
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)

Bash
git pull origin main
git push origin main
Why --rebase is usually better here
Using `--rebase` avoids a noisy merge commit for something as trivial as "syncing with remote". Your commits land on top of the remote commits as if you wrote them after.
4. CONFLICT (content): Merge conflict in...

Error output

Bash
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

Bash
# 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

Bash
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

Bash
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

Bash
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

Bash
git pull origin main --allow-unrelated-histories
# Git creates a merge commit joining the two histories

# Then push normally
git push origin main
Warning
Only use `--allow-unrelated-histories` when you genuinely want to join two separate repositories. Do not use it to silence the error if the real issue is that you cloned the wrong remote.
7. error: pathspec did not match any file(s) known to git

Error output

Bash
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

Bash
git add "my documents/notes.txt"

# Or escape the space:
git add my documents/notes.txt
8. Permission denied (publickey)

Error output

Bash
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

Bash
# 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

Bash
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

Bash
# 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
Warning
`git restore` discards your unsaved changes permanently. Only use it if you are sure you do not need those changes.
10. Updates were rejected because the tip of your current branch is behind

Error output

Bash
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

Bash
git fetch origin
git rebase origin/main
git push origin main
11. error: cannot pull with rebase: You have unstaged changes

Error output

Bash
git pull --rebase
# error: cannot pull with rebase: You have unstaged changes.
# Please commit or stash them.

Fix

Bash
git stash
git pull --rebase
git stash pop
12. fatal: remote origin already exists

Error output

Bash
git remote add origin https://github.com/user/repo.git
# fatal: remote origin already exists.

Fix

Bash
# 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

Bash
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

Bash
# 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

Bash
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

Bash
# 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

Bash
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

Bash
# 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
Warning
Do NOT use `git config --global http.sslVerify false`. This disables SSL verification entirely, exposing you to man-in-the-middle attacks. Only use the proper CA bundle approach or contact your IT team for the correct certificate.
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 -5 to understand the recent commit history.

  • Use git reflog to recover from mistakes — it records every HEAD movement.

  • Check git remote -v when push/pull issues are mysterious — you might be pointing at the wrong URL.