Common Git Errors and How to Avoid Them

4 Mins read

Common Git Errors and How to Avoid Them

A Version Control System (VCS) is an essential tool for almost any development team that needs to track changes in their source code.

Git was developed back in 2005 and today is by far the most commonly used VCS—almost all development teams that need to version and archive their source code use Git. Today, we will cover a few of the most common Git errors and discuss how you can potentially avoid or fix them.

Fatal: Not a Git Repository (or any of the Parent Directories)

This is one of the most common errors, especially for newcomers to Git. Let’s suppose you want to run git status in a particular directory:

$ git status

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

Fatal: not a git repository indicates that the command cannot be executed because the current directory is not a Git directory. Usually, you get this error due to one of two reasons.

  • You forgot to initialize the repository as a Git repository using git init
  • You are in the wrong directory. (You can check your current work directory using PWD. It’s quite common for people to forget to change directories when cloning a Git repository.)

Fatal: Refusing to Merge Unrelated Histories

Another very common error after git pull or git merge is the one shown below:

fatal: refusing to merge unrelated histories

This usually can happen mainly for one of two reasons:

  • The .git directory got corrupted. This hidden directory contains information relevant to your project that is being version controlled (for example, information about commits, remote repositories, etc.). If the directory is corrupted, Git is unaware of the local history. Thus, the error is reported when you try to push to or pull from a remote repository.

  • You are trying to pull from a remote repository that already has committed while you have also created a new repository locally and added commits. In such a case, the error is reported since Git is unaware of how these two are related (they are interpreted as two distinct projects).

If this is the case, you need to provide the –allow-unrelated-histories flag. For example,

$ git pull origin master –allow-unrelated-histories

There’s also a chance of getting this error when you are trying to rebase and require a different treatment.

$ git rebase origin/development

fatal: refusing to merge unrelated histories

Error redoing merge 1234deadbeef1234deadbeef

The process of combining commits to a new base commit is called rebasing. In other words, rebasing changes the branch’s base to a different commit so that it appears as if you have created a branch from that particular commit. The diagram below illustrates how rebasing work in Git.

Common Git Errors and How to Avoid Them

When git rebase fails with this error, rebase does not get aborted. It is still in progress. So, you can instead intervene manually.

$ git status

interactive rebase in progress; onto 4321beefdead

The last command done (1 command done):

pick 1234deadbeef1234deadbeef test merge commit

To solve this issue, you first need to merge and commit, and finally, force rebase to continue:

$ git merge –allow-unrelated ORIGINAL_BRANCH_THAT_WAS_MERGED –no-commit


$ git rebase –continue

Xcrun: Error: Invalid Active Developer Path

This is a common error for OSX users that becomes even more frequent when a new major OSX release is made. The error is reported when you attempt to run any git command. For example,

$ git status

xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun

The issue is related to the XCode Command Line Tools version that needs to be updated to resolve the error. To do so, open the terminal and run:

$ xcode-select –install

The response should be:

xcode-select: note: install requested for command line developer tools

Simultaneously, a pop-up window will appear on your screen asking you to confirm that you want to install command line developer tools.

Common Git Errors and How to Avoid Them

Simply click install, wait for the installation to complete, and open a new terminal session. Git commands should now work as expected.

Fatal: Unable to Create ‘.git/index.lock’: File Exists

When a git process crashes in one of your Git repositories, you may see the following error when you attempt to run a git command thereafter:

fatal: Unable to create ‘/path/to/.git/index.lock’: File exists.

If no other git process is currently operational, that implies a git process crashed in this repository earlier.

You can quickly fix this by manually removing the file:

$ rm -f .git/index.lock

Error: Pathspec Did Not Match any File(s) Known to Git

Usually, when you create a new branch using, say, the web UI of GitHub, and go back to your local terminal to checkout to the branch using the following command

$ git checkout mybranch

you may get this error:

error: pathspec ‘mybranch’ did not match any file(s) known to git.

This usually means that your local repository is not updated with the latest information for the remote Git repository. To fix the issue, you need to fetch the information for the newly created branch:

$ git fetch

Now, git checkout should work fine.

Permission Denied (Publickey)

To clone remote repositories to your local machine, you need to ensure that you have properly configured authentication.

At times, when you attempt to clone a repo, you get the following response:

$ git clone

Initialized empty Git repository in `/path/to/test/.git/`

Permission denied (publickey).

fatal: The remote end hung up unexpectedly

Now, there are potentially a couple of ways to resolve this issue. The easiest way is probably to use HTTPS instead to clone the repository to your local machine, which requires no public key validation:


Alternatively, if you still need to use SSH to clone the repository, you’ll have to generate SSH public and private keys to configure proper authentication. To do so, make sure to follow the steps below.

Navigate to your local .ssh directory and run ssh-keygen to generate keys

$ cd ~/.ssh && ssh-keygen

Now, copy the content of the generated file


$ cat | pbcopy

# Linux

$ cat | clip

# Windows

$ cat | clip

Add the key to the appropriate section on the GitHub website

Make sure your git configuration is correct

$ git config –global “your-user-name”

$ git config –global

And you should now be able to clone the remote repository using SSH. For more details, you may refer to GitHub documentation.

Final Thoughts

In today’s article, we explored a few of the most common errors in Git. For each of them, we discussed potential reasons as to why these errors are being triggered and how to fix them.

Git is a potent tool and is way more complicated than it looks. The community is great, and the internet is full of resources to help you resolve any issue you may have with Git.

Leave a Reply

Your email address will not be published. Required fields are marked *