The first part of this page describes the specific network and connectivity errors that can be diagnosed automatically by application links and the actions you can take to correct those errors.

The second part provides a general troubleshooting guide to help you identify and correct network and connectivity errors that may occur when using application links.

On this page:

Common network and connection errors

Unable to reach the remote application

The application link was attempting to connect to the remote application but the hostname of the remote application couldn't be resolved.

You may see this error message in the Atlassian application logs:

java.net.UnknownHostException: Unable to resolve host
Possible causes
Actions you can take
Misconfigured DNS.

Check your DNS configuration, particularly for private networks.

See nslookup below.

The application URL for the remote application is misconfigured, or may have changed recently.

Check the application URL of the remote application:

  • Is the host name correct?
  • Is the port correct?
  • Is the context path correct?
  • Does the application URL match the base URL for the remote application (or the display URL if the remote application is behind a reverse proxy)?

Back to top

 

 

The remote application is not responding

The application link was attempting to connect to the remote application but the connection was refused.

You may see this error message in the Atlassian application logs:

java.net.ConnectException: Connection refused
Possible causes
Actions you can take
The remote application is down.
  • Check that the remote application is operational, by accessing it from the browser using the application URL (or the display URL if the remote application is behind a reverse proxy).
  • If the remote application is not accessible with the browser, ping the remote application URL from the local server – the remote application must be accessible using the application URL for the application link to work. See ping below.

The application URL is misconfigured.

Check the application URL configuration at the local end:

  • Does the application URL use the correct port?
  • If you're using the IP address for the application URL, is that correct?
  • Does the application URL match the base URL of the remote application (or the display URL if the remote application is behind a reverse proxy )?
  • Does the application URL use the correct context path?
A firewall is blocking access.

Check that the firewall configuration allows access on the required port, using the network tools described below.

Back to top

 

 

A firewall is blocking requests

The application link was attempting to connect to the remote application but requests to the remote application are being blocked by a firewall in your network.

You may see an HTTP 405 message in your browser.

 

Possible causes
Actions you can take

A firewall is blocking requests.

  • Check that the firewall configuration allows HTTP requests (such as PUT) on the required port.

Back to top

 

 

Network request timed out

The application link was able to contact the remote application but could not establish a connection.

You may see this error message in the Atlassian application logs:

java.net.ConnectException: connect timed out
Possible causes
Actions you can take

The remote application is in deadlock.

  • Check that the remote application is operational, by accessing it as usual from the browser.

A firewall is blocking requests.

  • Check that the firewall configuration allows HTTP requests on the required port.

Back to top

 

 

Unable to locate the remote application

The application link was attempting to connect to the remote application but couldn't even contact it.

You may see this error message in the Atlassian application logs:

java.net.NoRouteToHostException
Possible causes
Actions you can take

A firewall is blocking requests.

  • Check that the firewall configuration allows access on the required port.
  • Use a tool like traceroute, described below, to show the path of traffic between the local and remote machines.
An intermediate router is down.
  • Use a tool like traceroute, described below, to show the path of traffic between the local and remote machines.

Back to top

 

 

Network response timed out

The application link was able to establish a connection with the remote application but no response was received.

You may see this error message in the Atlassian application logs:

java.net.SocketTimeoutException: connect timed out
Possible causes
Actions you can take

The remote application is in deadlock.

  • Check that the remote application is operational, by accessing it as usual from the browser.
There is a network connection problem.
  • Use the tools described below to check the connection with the remote machine.

Back to top

 

 

Unexpected response

The application link was attempting to connect to the remote application but an unexpected HTTP response was received. For many cases, this indicates that the remote application is behind a proxy that only provides HTTP 50x responses.

You may see these error messages in the Atlassian application logs:

UNEXPECTED_RESPONSE
UNEXPECTED_RESPONSE_STATUS
<response code>
<response body>
Possible causes
Actions you can take
HTTP 403: Forbidden
  • This usually indicates an authentication failure. However application links report authentication failures differently from a 403, so this suggests a problem with the proxy configuration instead.
HTTP 404: Page not found
  • The application URL used to configure the application link is not correct, or the application's address has changed.
  • Check that the application URL used to configure the application link is correct for the remote application.
HTTP 405: Method not allowed
  • A firewall or proxy is preventing HTTP requests.
  • Check the firewall or proxy configuration to see if HTTP requests (such as PUT) are allowed on the required port.
  • See A firewall is blocking requests above.
HTTP 500: Internal server error
  • The remote application may not be behind a proxy, but the application may have an error, such as an out of memory error.
  • Check that the remote application is operational, by accessing it as usual from the browser.
  • Check the application error logs.
HTTP 503: Service unavailable
  • The remote application is behind a proxy and is down.
  • Check that the remote application is operational by accessing it directly from your browser.
  • Restart the remote application, or contact your administrator.
  • See The remote application is not responding above.
HTTP 504: Gateway timeout
  • The remote application is behind a proxy and has timed out.
  • Try again later.
  • Check that the remote application is operational, by accessing it as usual from the browser.
  • Restart the remote application if necessary, or contact your administrator.
No status, or a different status from any of the above
  • The remote application is behind a misconfigured proxy. Check the local application logs for the <response body>.
  • The remote application is not actually of the type selected when configuring the application link. Check that the Application Type for the application link matches the remote application type. If it doesn't, you'll need to recreate the application link, making sure to choose the correct option for Application Type. See Link Atlassian applications to work together.

Back to top

 

Use the general troubleshooting guide below to help solve application links connection problems that are not covered by the common error types above.

Possible causeAction you can take

The server that hosts the application is not running.

  • Check that the remote server is actually running.

One or both servers are not actually connected to the network.

  • Check that you can reach each server by pinging each server from the other. See ping below.

The server that hosts the application is running, but it is not listening on the port that the application is trying to connect to.

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

  • Use telnet to test that the remote server accepts connections on a specific port.

The address and port combination for the server that hosts the remote application is incorrect or has changed.

  • Check the current location of the remote server.

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

  • Check the connector directive in the server.xml   configuration file for the remote application.

 

Error messages in the logs

You may see these error messages in the application logs (or the browser window for the HTTP messages):

Follow a link above for detailed information on this page.

Application log locations

Logging configurationApplication logsTomcat webserver logs
Bamboo <Bamboo installation directory> /logs  
Bitbucket Server / Stash

<Bitbucket home directory>/log

<Stash home directory>/log

<Bitbucket Server installation directory>/logs

<Stash installation directory>/logs

Confluence <Confluence home directory>/logs <Confluence installation directory >/logs
Crowd <Crowd home directory>/logs <Crowd installation directory>/apache-tomcat/logs
Crucible <Crucible installation  directory>/var/log/  
Fisheye <FishEye installation  directory>/var/log/  
JIRA applications <JIRA application home directory>/log <JIRA application installation directory>/logs

Consider enabling the DEBUG level of logging on the application to get more detailed logs – DEBUG adds all stack traces, and includes HTTP response messages.

 

Server.xml locations

The location of your server.xml file depends on your application, operating system, and installation location. 

Common default installation locations for Atlassian applications are:

  • Linux: /opt/atlassian/<application-name>
  • Windows: C:\Program Files\Atlassian\<application-name>
  • Windows: C:\Atlassian\<application-name>

Locations in Atlassian application's folder structure:

Applicationserver.xml location
Bamboo<install-path>/conf/
Confluence<install-path>/conf/
Crowd<install-path>/apache-tomcat/conf/
CrucibleAs for Fisheye.
FisheyeThe Fisheye configuration file is config.xml, see Configuring the Fisheye web server and How to enable Fisheye/Crucible to listen to web requests on additional ports.
JIRA applications<install-path>/conf/
Bitbucket Server 5.0

N/A, replaced by <Bitbucket home directory>/shared/bitbucket.properties

Please read through Migrate server.xml customizations to bitbucket.properties

Bitbucket Server 4.0 – 4.14<Bitbucket home directory> /shared/server.xml
Stash 3.8 – 3.11

<Stash home directory>/shared/

If you are on any of these later releases but your server.xml does not exist in the directory above, it means that you are running from the <install-path>/conf/server.xml.

We recommend that you copy <install-path>/conf/server.xml into <Stash home directory>/shared/ that way you won't need to worry about this when you upgrade your instance.


Stash 3.7 and earlier<install-path>/conf/

<install-path> refers to where the application was installed on your system.

 

Network connection tools

You can test the network connection between two machines using the tools described below. The objective is to check that:

  • Each machine can communicate with the other.
  • The required ports are open and connections can be made to them.
  • Each application is able to communicate with the other using a particular hostname/address and port combination.

  • Any firewalls or other network devices between each application have been configured to permit traffic between them.

Alternatively, you may wish to bypass certain network configurations and create an unproxied application link.

The pingcommand sends a small packet to the destination address, and notes the time it takes to respond. You can use ping to check the following:

  • Network connection - if ping succeeds, then both machines are connected to the network.
  • Correct DNS resolution - does the hostname (such as atlassian.com ) resolve to an IP address, and is it the correct one?
  • Response time between the machine issuing the ping, and the destination. Lower response times are better.

Failure to respond to a ping isn't necessarily an indication that the server is offline or down – it simply may not be responding to ping requests.

The traceroute ( tracert on Windows) command shows the flow of traffic between the current machine and the destination. Trace routes are particularly effective at identifying segments of poor performance or congestion.

The telnet command can be used to test that a host accepts a connection on a specific port. The telnet command is typically used like this:

telnet <host> <port>

Example:

telnet atlassian.com 80

When successfully connected to a host on the specified port, the output is similar to the following:

telnet host.example 80
Trying 192.168.1.100...
Connected to host.example.
Escape character is '^]'.

Once connected to the host and specified port, you can exit the telnet session. The purpose is to ensure you can connect over the specified port. Firewalls or other network configurations will reject the connection.

Telnet is not installed by default on Microsoft Windows.

  • Use "Turn Windows features on or off" in Windows 7 to install Telnet
  • In Server editions of Windows, use "Server Manager" to install Telnet

The nslookup command is used for querying the Domain Name System (DNS) to obtain domain name or IP address mappings. It allows you to check if the remote server's DNS name can be resolved from the local server.

Typically, you run nslookup from each server and check that the correct IP address for the other server is returned.

If the remote DNS name can't be resolved you'll need to get the DNS entry for each server updated.

If your servers connect over HTTPS you may need to consider updating the host address common name for your SSL certificates as well.

  • No labels
 




 

Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 2.5 Australia License.