Git error - Fatal: remote origin already exists and how to fix it

{{text-cta}}

"Remote origin already exists" error

The error `fatal: remote origin already exists` is caused when you attempt to create a link to a remote repository called “origin” when a remote link with that name is already configured.

The solution is to update the URL of the remote repository with the name “origin” to the URL of the remote repository you want to add, instead of trying to create a new remote repository with that name.

You can do that with this command:

git remote set-url origin https://github.com/your/repository

‍
It’s possible to inadvertently configure your local repository wrong if you don’t totally get what the commands that you’re running mean, or if you cloned a repository that already has a remote with the name “origin” configured.

To help you avoid making this mistake again, let’s unpack the concept of remote repositories a little. This error is usually caused by misunderstanding one of several things: what a remote repository is, how the `remote` command works, or more specifically what “origin” part of these commands means.

What is a remote repository?

To understand what a remote repository is, it’s important to first understand that Git stores and operates on your data in your local file system. In fact, Git is referred to as a distributed version control system because the source code is stored, or distributed, locally across any number of computers and servers. This is different from many of the source control tools that preceded Git.

Those tools were known as centralized version control systems (SVN or Subversion are the most well known examples), and they only operated on data hosted on a server by uploading changes in real time.

This meant that everybody always had access to the same data, because they were all working from the same server, but changes were slow to update and relied on a stable internet connection at all times.

Because all work stored in a Git repository lives in your local file system, source control operations are blazing fast and don’t require an internet connection, since you don’t upload each change to a server as it happens. The tradeoff is that your code isn’t easily accessible to others, so you need to regularly upload your changes to a server in order for other people to access them.

This is where remote repositories, or remotes, come in. A remote repository is a Git repository that lives on a server and is set up to be a mirror of your local work. Every time you run the `git push` command, you push your latest changes into that remote repository. Then, when somebody pulls from that remote repository, they receive your changes and end up with the same code you have.

This means that your code usually lives in multiple places -- in your local Git repository, in the remote one living on the server (GitHub is the most well known server), and in the file system of anybody else who has downloaded your work from the remote repository into a local repository of their own.

In a nutshell, a remote repository is where you upload your locally stored changes so that others can access them.

How does the "remote" tool work?

Now that we’ve covered what a remote repository is and why it’s necessary, it’s time to talk about how you can attach one to your local repository. Usually, this isn’t something that happens automatically -- you need to configure remotes by hand

Git’s `remote` tool provides a number of commands to configure remotes: add, remove, rename, etc. You can read the full documentation here, but for the purposes of solving the error this article is about, we are going to be most concerned with “add”, “remove”, and “reset-url”.

Let’s cover the few specific use-cases relevant to us briefly below:

git remote add <name> <url> is going to be the most commonly used command. This is how you can attach a remote to your repository. It associates the “url” parameter with the “name” you pass in. Looks like this, as you probably already know:

git remote add origin https://github.com/username/remote-repository

git remote remove <name> is pretty self-explanatory, and is also used frequently. If you don’t want to have a particular remote attached to your repository, just pass its name to this command and that remote will be completely removed. It won’t persist in history, caching or anywhere else:

git remote remove origin

In theory, you could remove the `origin` remote and then re-add it, but instead of doing that in two steps, you can actually knock it out in just one with the `set-url` command that I showed you at the top of this article. In one step, this command will update the URL of a repository for the given name you pass in.

Just for an example, if we were to list the remotes with `git remote --verbose` before and after running this command, they might look like this:

origin	https://github.com/your/repository (fetch)
origin	https://github.com/your/repository (push)

Let’s run the `set-url` command:

git remote set-url origin https://github.com/your-other/repository

‍
And looking at the list again:

origin	https://github.com/your-other/repository (fetch)
origin	https://github.com/your-other/repository (push)

{{text-cta}}

“origin” is a convention, not a part of the `git remote` command

It’s worth noting that using “origin” for the name of your default remote repository is simply a convention -- you could name your default remote “cheese” for all the difference it would make.

It’s frustrating, because this convention is actually the primary source of remote naming errors. At first glance it’s not obvious whether “origin” is part of the `git remote` command or just a parameter, a misconception that is further supported by the wording of the Git error: it’s not obvious that “origin” is a parameter, and not a part of the failing command.

And yes, this means that the error thrown at the top of the article could just as easily read “fatal: remote cheese already exists.”

Remote “origin” might've been configured if you cloned the repo

Since “origin” is such a common convention, there’s a good chance that any repository you clone already has a remote configured with this name, because remotes are included when a repository is cloned.‍

Cloning a repository and trying to add your own remote server to “origin” without realizing that that name is already in use is a very common way this error is caused. And again -- the solution is to use `git remote set-url` instead of `git remote add`.

Conclusion

As I mentioned at the beginning of this article, we broke down the concept of remote repositories in Git and went over a few of the most common commands that you’ll need to understand in order to use them properly. For further reading, you can find formal documentation on the `git remote` command here.

Nota bene: It’s easy to just copy and paste random bits of code that you find on Google to quickly fix the error, but generally speaking it’s much more useful to understand the underlying concepts so that you don’t have to keep Googling the same commands over and over again. So, if anything is still confusing, I’d encourage you to re-read this article and dig into the documentation linked above, as well as try out the examples and everything else you find for yourself. 

I hope this helps, and good luck!