Troubleshoot Bitbucket Smart Mirroring

Smart mirroring is being deprecated

Starting on April 21, 2021, smart mirroring in Bitbucket Cloud will no longer be available for new installations. Existing installations will continue to function as usual, but we will no longer be supporting this feature.

This page describes how to identify and solve problems you may have with Bitbucket Cloud Smart Mirroring: For further reference, read the Bitbucket Data Center FAQ.

General connection errors

This table lists the basic problems that can prevent communication between Bitbucket Cloud and your Smart Mirror:

Possible cause

Action you can take

The mirror server is not running.

  • Check that the server hosting the mirror is actually running.

The mirror server is not actually connected to the network.

  • Check that you can reach the server by pinging it from outside the firewall.

A firewall or other network device is blocking connections that use the particular combination of host address and port.

Note that outgoing calls from Bitbucket are incoming calls for the mirror. Similarly, outgoing calls from the mirror are incoming calls for Bitbucket. Both need to work.

  • Incoming: Use telnet to test that the mirror accepts incoming connections on a specific port.

  • Incoming: Check your network setup to ensure that Bitbucket can communicate with the mirror. The IP addresses that Bitbucket will use are listed on Bitbucket Cloud IP addresses.

  • Outgoing: SSH into the mirror server and check that it can connect to

  • Outgoing: advertises IPv6 addresses. If you are using IPv6 ensure that it is correctly configured.

The protocol being used to make the connection is incorrect (for example, it uses HTTP instead of HTTPS).

  • Check the configuration of the Server connector directive in the configuration file for the mirror application
    This file is in $BITBUCKET_HOME/shared/, where the $BITBUCKET_HOME environment variable contains the path to the Bitbucket Data Center home directory.

    The following lines should be added:

1 2 3 4 5 server.port=7990 server.proxy-name=<> server.scheme=https server.proxy-port=443

See Bitbucket Data Center config properties for more information.

The mirror application is running, but it's not listening on the port that Bitbucket Cloud is trying to connect to.

General SSL errors

There are some minimum requirements that your SSL certificate must meet:

  • The certificate common name (CN) must match the host name (the URL address) for the application.

  • The certificate timestamp must still be valid.

  • The certificate must be installed into the correct Java trust store (Bitbucket Data Center is a Java application that bundles the Tomcat application server). To check that certificates are present in the Java trust store see Check the SSL certificate location.

  • Make sure that your key and certificate are correctly configured in either the mirror or your HTTPS proxy. See See of the options in Securing a reverse proxy using HTTPS for SSL configuration details.

To see details of a certificate, visit the application in your browser and click the padlock in the browser address bar. You can also check SSL certificate details online (for example using

General browser issues

Under some circumstances you may experience problems when using the mirror administration UI, such as:

  • Adding projects to, or removing projects from, the mirror fails to add some projects and displays an error message prompting you to refresh the page to try adding the projects again.

  • When trying to use the Mirror Support tools, you receive an error message notifying you that you are not logged in and to log in to continue using this tool.

Both of these problems can occur if your browser does not allow third-party cookies. The workaround is to enable third-party cookies – see BSERV-8558 for details.

No valid HTTPS configuration

Incorrectly set Mirror base URL

  • The property Mirror base URL can only be set once. It gets set by the wizard that runs when you first start Bitbucket Data Center. If configured incorrectly, or you need to change it, you'll need to delete your mirror and set it up again.

Unknown public key

When cloning or pulling from the Bitbucket mirror you may see the following error message in a terminal:

1 2 3 Cloning into 'local-repo'... Permission denied (publickey). fatal: Could not read from remote repository.

Possible causes

Actions you can take

Missing public key

Unsupported SSH key type

  • Check the type of SSH key you use to authenticate with the mirror. Bitbucket Cloud mirroring supports the RSA, DSA and ECDSA SSH key types. ED25519 keys are not supported by Bitbucket Data Center (the mirror). Look inside your public key and check that it doesn't start with ssh-ed25519. For details on how to find your public key see Troubleshoot SSH issues.

  • A workaround is to configure another key, of a supported type, and use that for the mirror. See Set up an SSH key.


Additional Help