Troubleshooting Bitbucket Git issues

Related content

Still need help?

The Atlassian Community is here for you.

Ask the community

This page provides self-serve troubleshooting steps for GIT failures and other common issues.


Scenario 1: HTTPS error while trying to clone with SSH in Bitbucket Cloud

User is getting below HTTPS error while trying to clone using SSH. 

remote: You may not have access to this repository or it no longer exists in this workspace. If you think this repository exists and you have access, make sure you are authenticated.
fatal: repository 'https://bitbucket.org/WORKSPACEID/REPO.git/' not found

There are no access issues either. 

Possible causes:

By reviewing the error message, it is evident that the SSH URL id replaced with the incorrect HTTPS URL. Due to this incorrect replacement, the issue occurs even though the user was trying to perform the SSH clone.

This issues is observed when user configures an incorrect HTTPS URL in the insteadOf parameter for SSH in Git's configuration. The insteadOf parameter is used to rewrite URLs for specific Git remotes. It allows replacement of a part of a URL with another string when Git fetches, pushes, or clones repositories. 

Troubleshooting Steps:

YES (tick)

  • Check the GIT configuration for the insteadOf parameter.
  • If any values are incorrectly added, ensure to remove the configuration by opening the GIT config in any of the editors.

  • The GIT configurations can checked by running the below command:

    git config --list --show-scope

NO (error)


Scenario 2: Cannot GIT push - Broken link from tree to blob

User attempting to push a commit to a remote repository encounters some variant of the following error message:

fatal: unable to read 18d62d26762787ca2d00bca6eabcba76023019c1
aborting due to possible repository corruption on the remote side.
git upload-pack: git-pack-objects died with error.

Possible causes:

  • When a file is not written properly to the GIT object database, either because of a hardware/network failure or another issue - this can result in potential repository corruption.
  • The issue is GIT related and is not Bitbucket-specific as such, it can occur on any SCM that uses GIT.

Troubleshooting Steps:

The first step will be to identify exactly where the potential corruption is, this can be done by running a GIT file system integrity check command locally and observing the results:

# git fsck --full --strict
Checking object directories: 100% (256/256), done.
Checking objects: 100% (1394358/1394358), done.
broken link from    tree 98068c4d5f2513ada367ac2a5979e3ac238dd911
              to    blob 18d62d26762787ca2d00bca6eabcba76023019c1

Once user has the resulting error (usually an issue with the GIT working tree as above), user can begin to resolve the issue.

There are a few ways to resolve an issue such as the above.

Solution #1 - Attempt to repair the object database

  1. Once the tree/blob details are available from the file system check command above, use this to check the tree that the blob belongs to and find the filename of that specific blob from the list of blobs within the tree as shown below:

    # git ls-tree 98068c4d5f2513ada367ac2a5979e3ac238dd911
blob 18d62d26762787ca2d00bca6eabcba76023019c1 code.java

  2.  Once the problematic file has been tracked down, attempt to have GIT locate the unique SHA-1 hash that belongs to that file and write it to the object database (with the -w switch):

    git hash-object -w code.java
  3. If a SHA-1 hash is returned by the above command, the issue is resolved and a subsequent file system check will reveal this.

If this solution did not fix the issue, please continue to Solution #2 (if working as part of a team) or Solution #3 (if not working in a team).

Solution #2 - Force push 

There is a chance that a team member has a working copy of the local repository prior to the corruption, and fixing the missing blob(s) is as easy as pushing these back to the repository.

  1. Consult with the team and ask them to execute the same file checking command against their local repository:

    git fsck --full --strict

  2. If there are no errors in the above step, try to force push their working copy of the local repository up to the remote repository to resolve the issue (perform a clone backup of the repository first just in case):

    git push -f origin --all
  3. Once the push completes, users facing the the error can then perform a fresh clone of the repository and verify once again with the file system checking command that there are now no errors present.

Solution #3 - Restore from backup

If all other avenues fail, the support team will be able to restore a backup copy of the repository.

  • As per our backup policy we maintain repository backups for 7 days, and these consist of hourly snapshots of the core repository content.

  • Please feel free to raise a support ticket or raise a community support ticket and we can restore the repository prior to the corruption issue if done within 7 days of the corruption.

NOTE: This option is time sensitive, so please make the decision to restore within this 7-day period to avoid any potential data loss.

NO (error)


Scenario 3: Fix error "fatal: No url found for submodule path in .gitmodules"

When a user updates their .gitmodules file to point to a new path for their submodule in another repository and then attempts to update the git submodules in the remote repository (either using GIT or in Bitbucket Cloud Pipelines) by using some variation of the following command:

git submodule update --init --recursive

They encounter the following error message - which points to the old path that was previously referenced in their .gitmodules file:

fatal: No url found for submodule path 'x' in .gitmodules

Possible causes:

  • Essentially, the root cause of the issue is that either the old submodule path remains cached (and must be be removed) or a path does not exist (and must be created) before the submodules may be updated.

Troubleshooting Steps:

Is a PATH variable defined as in Workspace, Repository, or Deployment variables?

YES (tick)

To check this, perform the following on the local repository:

  1. Check the currently configured git submodules by executing the following to verify the submodule path status:

    git submodule status

    If the old path is present:
    Execute the following command to remove the old submodule path from the cache:

    git rm --cached old/path

    If no path is present:
    To create the mapping reference, enter the following into .gitmodules file in root of the repository:

    [submodule "path_to_submodule"] 
  path = path_to_submodule 
  url = git://url-of-source/

    path_to_submodule: is the actual path within the repository (relative to the root) where the submodule will be used
    url-of-source: is the URL of the original repository that contains the submodule's files.

  2. Once the above steps have been performed, double-check the path configuration before updating the submodules:

    git submodule status

  3. Once complete, execute the same submodule command ran earlier, and the user should not get any error:

    git submodule update --init --recursive
  4. Now that the .gitmodules file has been updated with the new path or old path has been removed from cache/updated in the config, commit the changes and push them to the remote repository to resolve the issue.

NO (error)


Scenario 4: Command "git archive" Failure

When attempting to use the native git archive utility, some errors may appear, preventing the archive to complete.

Troubleshooting Steps:

Scenario 4.1 (SSH)

An attempted archive may fail with the below "Cloud not resolve hostname" error.

git archive --output=outfile.txt --remote=ssh://git@bitbucket.org:atlassian/cloudtoken.git HEAD 
ssh: Could not resolve hostname bitbucket.org:atlassian: Name or service not known 
fatal: the remote end hung up unexpectedly

Cause

This is caused by the format of the "remote" string containing two ":" characters. 

Solution

This can be resolved by adjusting the remote string to use either of the below syntaxes.

# Accepted formats: 


git archive --output=outfile.txt --remote=ssh://git@bitbucket.org/atlassian/cloudtoken.git HEAD 
# Continue to use the "ssh://" prefix and adjust the later ":" to a "/" between the hostname and your workspace ID 

git archive --output=outfile.txt --remote=git@bitbucket.org:atlassian/cloudtoken.git HEAD 
# Remove the "ssh://" prefix and use a ":" between the hostname and your workspae ID

Scenario 4.2 (HTTP)

An attempted archive may fail with the below "operation not supported by protocol" error.

git archive --output=outfile.txt --remote=https://your-username@bitbucket.org/atlassian/cloudtoken.git HEAD
fatal: operation not supported by protocol

Cause

The Bitbucket Cloud platform does not support git archive over the HTTP(s) protocol.

Solution

Use the SSH protocol as mentioned in Case #1 above instead

NO (error)


Scenario 5: Creation of branch with / in the name fails

Creation of branch fails with the following error

fatal: cannot lock ref 'refs/heads/dev/feature1': 'refs/heads/dev' exists; cannot create 'refs/heads/dev/feature1'

Possible Causes:

This happens because of the way git stores pointers to the HEAD of each branch in the .git/refs/heads folder. In every git repository, there exists a .git/refs/heads folder, which contains a text file for each branch on the repository, that stores the commit hash for the tip of the branch.

For example, if the repository has three branches named master, dev and feature, the files in .git/refs/heads will look like this -

$ > ls .git/refs/heads 

dev feature master

Each of these files corresponds to a branch.

Creation of a new branch called "feature/first-feature" would mean creation of a file called "feature/first-feature". However, this would not be allowed since a file called feature already exists and hence git cannot create a file and a directory with the same name.

Troubleshooting Steps:

YES (tick)

To resolve this issue, there are two workarounds -

  • Delete the branch called feature if the user wants to create other branches like feature/feature-1 or feature/first-feature.
    Please make sure that this does not impact the code since this is a destructive action.

git push -d origin feature 
git branch -d feature

The first command deletes the remote branch. Please replace origin with the correct remote name if it is not origin.

The second command deletes the branch remotely. This command is not required if the branch has not been pushed to the remote yet.

  • Rename the local and remote branch from feature to feature/feature-1. Name the subsequent features as feature/feature-2 and so on. A branch called just feature cannot exist.
git branch -m feature feature/feature-1
git push -d origin feature
git branch --unset-upstream feature/feature-1
git push origin feature/feature-1
git push origin -u feature/feature-1

NO (error)


Scenario 6: Invalid path, fatal: unable to checkout working tree while cloning the repository in Windows

Unable to clone the repository in Windows and getting the below error:

error invalid path - filename 
fatal unable to checkout working tree

Possible causes:

Windows reserves certain file names. So when it tries to create a file that uses a reserved base name or uses special characters it will fail.

Please refer to the Naming a file Windows documentation:

Do not use the following reserved names for the name of a file:

CON, PRN, AUX, NUL, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, and LPT9. Also avoid these names followed immediately by an extension; for example, NUL.txt is not recommended

The following reserved characters:

    • < (less than)
    • > (greater than)
    • : (colon)
    • " (double quote)
    • / (forward slash)
    • \ (backslash)
    • | (vertical bar or pipe)
    • ? (question mark)
    • * (asterisk)

Troubleshooting Steps:

YES (tick)

  • User can check the git repository they are trying to clone and analyze if there are any file names consisting of the Windows Reserved Characters.
  • Rename the file by removing all the reserved characters in the remote git repository. 
  • Try cloning the repository again and it should clone without any issues. 

NO (error)


Scenario 7: Git push is rejected using SSH key with branch restrictions

Git push is rejected with below error whilst having write access in the repository branch restriction settings. The situation implies that there may be some issues with the branch restriction settings or the location of the Public SSH key being added to Bitbucket cloud.

! [remote rejected] feature/test-commit -> feature/test-commit (pre-receive hook declined)

Possible causes:

There are two places that need to be checked and verified for correct configuration:

  1. Branch restriction settings
  2. SSH key location

Start with the branch restriction settings first by identifying whether the user is in the group that is allowed to write to the branch. If not, manually add the user to the branch restriction settings.

If the above is correctly configured, identify where the Public SSH key was previously added. Check the following areas:

Troubleshooting Steps:

YES (tick)

If the public SSH key has been added in the workspace or repository settings, kindly remove it from there and add it to personal settings. This is because branch restriction requires information about the user who is making the changes in order to verify if they have access to make changes on the branch or not. The push will be rejected if the user's identity is unknown.

NO (error)


Scenario 8: SSL certificate problem: self-signed certificate in certificate chain error in GIT

While performing any GIT operations, the user receives the below error message:

SSL certificate problem: self-signed certificate in certificate chain

Possible causes:

  • The error message "self-signed certificate in certificate chain" usually indicates that the SSL certificate provided by the Git server the user is trying to connect to is not trusted by the Git client. This can occur if the certificate is self-signed, or if it is signed by an untrusted certificate authority.

Troubleshooting Steps:

YES (tick)

  • Configure Git to trust the self-signed certificate globally: Configure Git to trust the self-signed certificate globally by adding an 'http.sslCAInfo' setting to the Git configuration file. Here's an example of how to configure Git to trust a self-signed certificate:

    git config --global http.sslCAInfo /path/to/ca.pem

  • In case of Windows system, use the configuration below which sets the Secure Channel (schannel) library as the SSL backend for Git's HTTP communication.
    This setting is recommended on Windows systems, as the schannel library is a part of the Windows operating system and is well-integrated with its security features. Once configured, Git will use the Windows certificate store and should not require the http.sslCAInfo configuration setting.
    The git config --global http.sslBackend channel setting does not bypass SSL validation. It only sets the SSL backend used by Git for its HTTP communication. The schannel library, like other SSL backends, is designed to perform SSL validation by default, which includes verifying the authenticity of the SSL certificate presented by the remote server. The schannel library is considered to be a secure SSL backend, and it supports strong encryption algorithms and certificate validation.

    git config --global http.sslBackend schannel

NO (error)


Scenario 9: git error fatal: Unable to create '<path>/.git/index.lock': File exists.

When running git commands, user encounters see the following error pointing to a file: .git/index.lock. 

fatal: Unable to create '<path>/.git/index.lock': 
File exists.

If user is pushing to Bitbucket Cloud and get a similar error, but it is a remote error, make sure the error says 'remote error' and check to see if the file exists. If the file does not exist, the git process that created the file finished and exited, then this is not the right Knowledge Base Article to follow, please create a support ticket:

remote: error: cannot lock ref 'refs/heads/master': 
Unable to create '<path>/./refs/heads/master.lock': 
File exists.

Possible causes:

Another git process is currently writing data to this repository. 

OR 

A git process exited early and was not able to remove the file before exiting. This file is used to make sure two git process do not write at the same time.

Troubleshooting Steps:

YES (tick)

This issue is a local error, it affects just this repository. Check the OS to make sure no other git process are running.  Once confirmed that no git process are running, user can remove the file with no issues.

NO (error)




Last modified on Feb 26, 2024

Was this helpful?

Yes
No
Provide feedback about this article

Related content

Powered by Confluence and Scroll Viewport.