Troubleshooting Connection Issues for Elasticsearch

Still need help?

The Atlassian Community is here for you.

Ask the community

Platform notice: Server and Data Center only. This article only applies to Atlassian products on the Server and Data Center platforms.

Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.

*Except Fisheye and Crucible


Bitbucket Server is unable to connect to Elasticsearch.

One of the following log line appears in the atlassian-bitbucket.log:

  1. Connection refused

    DEBUG "POST /rest/search/latest/search HTTP/1.1" Connection exception: Connection refused: no further information
    DEBUG "POST /rest/search/latest/search HTTP/1.1" Timing: Search request execution took 1.023 s [1022 ms] for query 'XXX'
  2. HTTP 401 status code

    DefaultElasticsearchConnectionTester Testing connection with Elasticsearch failed: HTTP response status code is 401

This will cause a large error on the screen when performing a search.


Diagnostic Steps

  • There are no details in the Elasticsearch username and/or password fields
  • The option to let the installer startup Bitbucket Server was not chosen

If you are receiving 401 errors, these indicate that authentication issues are happening - meaning it's important to check if Bitbucket has been configured with the correct credentials to access Elasticsearch.

Once the application has started up, it's suggested that you fully execute a test of Elasticsearch at Administration (cog in the top right) → Server Settings → Test Elasticsearch Connection

If you receive the following error, then it's highly recommended you follow the steps listed in this knowledge article in order to help confirm that the credentials you're using are correct:


This depends on what error you were seeing in the logs:

Stacktrace #1 - Connection Refused

Elasticsearch was not started.

Stacktrace #2 - HTTP 401 Errors

This is due to the fact that Bitbucket Server started before Elasticsearch on the first-ever run. Therefore Bitbucket Server did not get to negotiate a username and password for Elasticsearch. This negotiation only happens during the Bitbucket Server startup. Therefore if it is missed, it doesn't get the chance to try again. This really only has to succeed once.


The resolution is the same for both cases and requires the following steps to be performed:

  1. Start Elasticsearch
  2. Restart Bitbucket Server 

The steps on how to perform the restart are detailed on the Start and stop Bitbucket page.

This will then mean that Elasticsearch is already waiting for Bitbucket Server to start up. Therefore when Bitbucket Server gets to the stage of startup where it attempts to negotiate a password, Elasticsearch will be ready to accept that connection.

  • In the case of using Remote Elasticsearch, Start the Elasticsearch services first and then start the Bitbucket application Services.
  • In case of using Bundled Elasticsearch, Restart the Bitbucket Application Services. Bundled Elasticsearch will be automatically started when the Bitbucket application service starts.

Bitbucket Server 5.0

As of Bitbucket Server 5.0, Bundled ElasticSearch is now automatically started when the Bitbucket application is started.


With a Windows service:

  • Restart ElasticSearch Service
  • Restart Bitbucket service

Without a Windows service:

In both cases you can solve your issues by following these steps:

> cd <Bitbucket Server installation directory>
> bin\stop-bitbucket.bat
> bin\start-bitbucket.bat

With a Linux service:

In both cases you can solve your issues by following these steps:

# service atlbitbucket stop
# service atlbitbucket start

Without a Linux service:

> cd <Bitbucket Server installation directory>
> bin/
> bin/

DescriptionBitbucket Server is unable to connect to Elasticsearch and will cause a large error on the screen when performing a search.
Last modified on Sep 5, 2022

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.