Troubleshooting Common Problems

Git's error messages look intimidating, but most come from a small set of situations — and Git usually suggests the fix in the message itself. Here are the problems people hit most often, with the real messages and what to do about each.

"not a git repository"

cd ~
git log

Output

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

You're outside the project folder (or the folder was never initialised). cd into the folder that contains .git; pwd tells you where you are.

"pathspec did not match any files"

cd ~/recipes
git add pancake.txt

Output

fatal: pathspec 'pancake.txt' did not match any files

A typo in a file name, or the wrong folder. Check with ls or git status, and use Tab to complete names.

"src refspec main does not match any"

cd ~
git init --quiet empty-project
cd empty-project
git remote add origin https://github.com/sam-rivera/recipes.git
git push -u origin main

Output

error: src refspec main does not match any
error: failed to push some refs to 'https://github.com/sam-rivera/recipes.git'

There's nothing to push: the branch has no commits yet (or it's called something else, such as master — check with git branch). Make a first commit, or push the branch by its real name.

"remote origin already exists"

cd ~/recipes
git remote add origin https://github.com/sam-rivera/recipes.git
git remote add origin https://github.com/sam-rivera/cookbook.git

Output

error: remote origin already exists.

A remote with that name is already set. To point it somewhere else, use git remote set-url origin <url>; check what's there with git remote -v.

Push rejected: "fetch first" or "non-fast-forward"

The remote has commits you don't. Run git pull (choose merge or rebase, lesson 34), resolve any conflicts, then push again. Don't reach for --force on a shared branch — it would delete your teammates' commits.

"refusing to merge unrelated histories"

Typically: you created a repository on GitHub with a README, and separately ran git init and committed locally. The two histories have no commit in common:

git pull origin main --no-rebase

Output

remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (3/3), 228 bytes | 228.00 KiB/s, done.
From https://github.com/sam-rivera/recipes
 * branch            main       -> FETCH_HEAD
 * [new branch]      main       -> origin/main
fatal: refusing to merge unrelated histories

If you really do want to combine them (usually you do, in this situation), allow it once:

git pull origin main --no-rebase --allow-unrelated-histories --no-edit

Output

From https://github.com/sam-rivera/recipes
 * branch            main       -> FETCH_HEAD
Merge made by the 'ort' strategy.
 pancakes.txt | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 pancakes.txt

"Your local changes would be overwritten"

A switch, pull or merge would change files you have edited but not committed. Commit them, stash them (git stash), or discard them (git restore), then try again (lesson 23).

"You are in 'detached HEAD' state"

You checked out a commit or tag rather than a branch. Looking around is fine. To keep any commits you make, create a branch: git switch -c new-branch. To leave, git switch main (lesson 23).

Stuck in an editor

A commit, merge or rebase opened Vim and you don't know how to get out: press Esc, type :wq and Enter to save and continue, or :cq to quit with an error, which cancels a commit or merge message. Then set an editor you like (lesson 3).

In the middle of something

If a merge, rebase, cherry-pick or revert stopped and you've lost track, run git status: it names the operation in progress and how to continue or abort.

In progress	Continue	Give up
merge	`git commit`	`git merge --abort`
rebase	`git rebase --continue`	`git rebase --abort`
cherry-pick	`git cherry-pick --continue`	`git cherry-pick --abort`
revert	`git revert --continue`	`git revert --abort`

"I committed to the wrong branch"

Sam meant to start a feature branch but committed on main (not pushed yet). Move the commit to a new branch and take main back:

echo "Brownies: chocolate, butter" > brownies.txt
git add . && git commit --quiet -m "Add brownie recipe"
git branch desserts
git reset --hard --quiet origin/main
git log --oneline --all --graph

Output

* b99ddbd (desserts) Add brownie recipe
* 6b13d64 (HEAD -> main, origin/main) Add pancake recipe

If the target branch already exists, cherry-pick the commit onto it instead (lesson 28), then reset main.

"I committed something I shouldn't have"

Not pushed: remove it from the last commit with git rm --cached file and git commit --amend; add it to .gitignore.
Pushed, and it's a secret: revoke or rotate the secret immediately — assume it's compromised. Then clean history with git filter-repo if needed (lesson 14).
Pushed, and it's just big: see lesson 47.

"LF will be replaced by CRLF"

A warning, not an error: Git is converting line endings according to your core.autocrlf setting. Add a .gitattributes file to make the rules explicit for everyone (lesson 43).

Lost commits

After a bad reset, rebase or branch deletion: git reflog, find the commit, and git branch rescue <hash> (lesson 20).

A troubleshooting routine

Read the whole message, including hint: lines — they often contain the exact fix.
Run git status and git log --oneline --graph --all -10 to see where you are.
Before anything risky, make a safety branch: git branch backup-before-fix.
Search the exact error message — someone has almost certainly hit it before.

Try it yourself

Deliberately cause three of the errors above in a test repository — say a wrong path, a duplicate remote and a commit on the wrong branch — and fix each one using the advice here.

PreviousCI with GitHub Actions NextBest Practices