Hopefully this article will save at least one other person an hour of their life trying to figure out why they cannot clone a Bitbucket repository when using SSH.

My projects are broken into several teams, each with their own developer and administrator users.  Each team has a number of repositories that are being managed.  There is one common denominator; I have admin access to all repositories.   That means my Bitbucket user should have full read/write/admin privileges on all repos.    Yet no matter how many different keys I added to my Bitbucket user account it would not allow me to clone several repositories.

For those that want the short answer of what worked… use the “long form” SSH URL.

git clone ssh://git@bitbucket.org/<team_or_user_account_name>/<repo_name>

While I typically use the “short form”, as noted below, this absolutely would NOT work for certain repositories or different pre-shared keys even on a repository that uses the “short form”.   Sadly the short form is what Bitbucket serves up when you look at the clone interface on their website.  Here is a short form of the above URL:

git clone git@bitbucket.org:<team_or_user_account_name>/<repo_name>

Secure Access To Repos

With private repositories you always want to use some form of authentication to prevent people with the URL from cloning your project.   Your options with Bitbucket are to use an API Key , use OAuth, or setup SSH access with shared keys.    API Keys can be nice but you need to have an app that will manage your “handshake” with Bitbucket and interface with your git app or sytem-level network stacks.   OAuth is similar but allows more control with a user/password type setup so you lock out one person whereas the API key is an “everybody/nobody” solution.    SSH is already setup on any system you will use and with a little effort you can quickly learn how to create your public/private keys and share them.

Setting Up SSH

For Linux/OSX systems you can quickly setup your SSH keys by logging into the account you will using to do the clone.    You will need a .ssh directory and will generate your SSH keys.    There are plenty of articles on how to do that including Set up SSH on the Bitbucket site.   In short you will run ssh-keygen, copy the id_rsa.pub contents and add it under your user account in Bitbucket.

Cloning Your Repo

Normally you can just go to your directory and do something like this:

git clone git@bitbucket.org:storelocatorplus/store-locator-plus.git

Maybe that is a bad example since that repository is wide open and won’t require security, but the concept is the same.    The problem is that for some repositories you get something like this:

Cloning into 'store-locator-plus'...
conq: invalid command syntax.
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

That is very special.  It appears to be unique to Bitbucket , though I’ve not researched that so don’t take that statement as fact.   It also seems to only occur if you are running ssh-agent as instructed on that “Set up SSH” article cited above.

If you are not running SSH you may see this instead:

Permission denied (publickey).
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

No “conq” but essentially the same message.

If you follow the “debugging SSH connections” article on Bitbucket they tell you to run the ssh -Tv git@bitbucket.org command to get some clues as to why your authentication failed.   The problem is that my SSH sessions were NOT failing when tracing the connection.  I was getting a valid connection to my user account on Bitbucket.

Finally, after all other possible solutions failed I tried the alternate URL format.   It cloned the repository.

git clone ssh://git@bitbucket.org/storelocatorplus/store-locator-plus.git

Magic.  Black magic.   Possibly even evil.   But it works.

Hopefully this saves you from creating a dozen different SSH keys on a half-dozen different servers.  It may save you from setting up alternate identities or complex SSH authentication models.   You probably don’t even need to run an ssh-agent if you only have a single key for your login.    In short this simple trick may save you a lot of frustration.

And some people wonder why I’m bald.   Lifestyle choice?  Nah.  I’m just another code geek that has been at this for a long time.