Application Links Troubleshooting Guide

Atlassian Knowledge Base

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

Application links are the connections that support most of the integrations between Atlassian server applications. Read more about using your Atlassian tools together at Streamline software development with Atlassian tools.

If you're just wanting to set up an application link see Link Atlassian applications to work together.


General checklist

1. Have you recently moved or changed anything in your environment?

If you've changed your environment, such as reverse proxies, physical servers or even URLs, it's best to recreate the link just in case. Recreating an application link doesn't remove any data. Existing macros, plugins and pages that make use of an application link will start working again once the application link has been recreated.

Note however that recreating the link will force all of your users to log in again.

2. Has there been a recent upgrade of an application?
If your application links have stopped working after a recent upgrade it's possible that your customizations to the application's server.xml file were overwritten. Custom changes can include reverse proxy configuration and HTTPS configuration. You should check that the upgraded server.xml file matches the pre-upgrade server.xml.

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.


3. Are you linking Atlassian Cloud applications?

If an application involved in your application link is hosted on Atlassian Cloud, there are a couple of considerations. Your local server must use a valid SSL certificate, and it must be accessible on port 80 or 443. For more information, see this Cloud documentation.

If you have a internet-facing firewall, make sure to allow the IP range used by Atlassian to reach your internal network. For up-to-date information on that, see Atlassian cloud IP ranges and domains.

4. Have you created a two-way application link between the applications?

Full integration between Atlassian applications, such as Bitbucket Server and Jira Software, requires a reciprocal (two-way) application link between the applications.

Both ends of the application link should use the same authentication mode. Atlassian only recommends OAuth authentication.

To get full integration when creating the application link you must check the box marked Also create a link... back to this serverenter your administrator credentials for the remote application, and then select your user base scenario to configure authentication.

If you think you've already set up application links in both directions, you can check that as follows:

  1. In the local application, go to Administration > Application Links and make sure there is an application link entry for your remote application.
  2. In the remote application, go to Administration > Application Links and make sure there is an application link entry pointing back to your local application.

See our instructions for how to create an application link at Link Atlassian applications to work together.

5. Can your local and remote applications see each other on the network?

If you local and remote applications are not able to communicate over the network you'll see NETWORK ERROR for the link on the Application Links Configuration page.

Refer to our Network and connectivity troubleshooting guide for detailed information about how to diagnose and fix connection problems.

6. Is you application link configured correctly for your network topology?

The configuration of an application link depends on whether your network includes firewalls, reverse proxies, load-balancers or other network devices or services.

In particular, the application URL used for the application link must be the URL that you use to access the remote application.

Refer to these pages for more information:

7. Are your application links properly authenticated?

You should use OAuth authentication for your application link. Atlassian no longer recommends using Basic HTTP authentication or Trusted Applications authentication.

Furthermore, both ends of the application link should use the same authentication configuration.

OAuth authentication is set by default for newly created application links, but you can modify an existing application link to use OAuth.

To check: 

  1. In the local application, click Administration > Application Links.
  2. Click Edit for the application link. Check the OAuth setup on the Incoming Authentication and Outgoing Authentication tabs for your application link.
  3. In the remote application, click Administration > Application Links.
  4. Again, click Edit for the application link. Check the OAuth setup on the Incoming Authentication and Outgoing Authentication tabs for your application link. Check that the Outgoing Authentication tab setup matches the Incoming Authentication setup of the local application, and vice-versa.

Refer to our OAuth Troubleshooting Guide for detailed information about how to diagnose and fix OAuth problems.

8. Are your users still prompted to log in even though you've set up an application link?

This scenario occurs when the authentication used by the application link doesn't allow the two applications to fully trust each other. You can fix this by:

  1. In the application that's prompting users to authenticate, change the Outgoing configuration setting for the application link to allow 2-Legged OAuth authentication.
  2. In the application that users are trying to connect to, change the Incoming configuration setting for the application link to allow 2-Legged OAuth authentication.

See Link Atlassian applications to work together for more information.

9. Are your servers synchronized?

Unsynchronized server times can break authentication.

  • Is the time and date significantly different between each machine? Consider using a Network Time Server to ensure all machines are in synchronization.
  • Is each machine aware of the time zone that it's in? Invalid time zones can cause problems during OAuth authentication.

Refer to our OAuth Troubleshooting Guide for detailed information.

10. Should you use impersonation with your application link?

2-Legged OAuth with Impersonation (2LOi) is recommended when you require an application to use impersonation (such as Jira Service Desk); or when you wish to avoid the confirmation prompts when accessing information across applications.

You should enable impersonation:

  • When the user bases between each application are identical.
  • When using applications that require impersonation, such as Jira Service Desk.

See OAuth security for application links for more information.

11. Do your local and remote applications communicate over a secure (HTTPS) connection?
Refer to our SSL and application link troubleshooting guide for detailed information about how to diagnose and fix SSL problems with application links.
12. Have you checked the logs for error messages?

Atlassian server products are Java applications that bundle the Tomcat application server. Both the application and Tomcat generate logs that can help to diagnose a problem with application links.

Click to see 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.

You can use the error messages in the logs to find the relevant solution to your problem on one of these pages:

13. Finally, recreate the link...

Recreating the link ensures that the application link uses any configuration changes you've made while troubleshooting a problem.

Note: Deleting or modifying an application link is a non-destructive process. Any existing macros or gadgets will resume functioning once the link has been recreated correctly. No content is removed as a result of removing an application link.

However, note that:

  • Deleting then recreating an application link will force all of your users to log in again.
  • If your instance has Project Links defined, these will be deleted along with the application link. They must be recreated after the application link has been recreated.

See Delete an application link for instructions.

See Link Atlassian applications to work together for instructions.


Network and connection troubleshooting

The 'Configure Application Links' screen in Atlassian products provides diagnostics for the following network and connection problems that can occur with application links:

Follow the links above for diagnostics and specific actions you can take to resolve these connection problems.

Otherwise, see our Network and connectivity troubleshooting guide for general solutions or see the error messages related to network and connection problems.


OAuth troubleshooting

The 'Configure Application Links' screen in Atlassian products provides diagnostics for the following OAuth problems that can occur with application links:

Follow the links above for diagnostics and specific actions you can take to resolve these OAuth problems.

Otherwise, see our OAuth troubleshooting guide for general solutions or see the error messages related to OAuth problems.


SSL troubleshooting

The 'Configure Application Links' screen in Atlassian products provides diagnostics for the following SSL problems that can occur with application links:

Follow the links above for diagnostics and specific actions you can take to resolve these SSL problems.

Otherwise, see our SSL and application link troubleshooting guide for general solutions or see the error messages related to SSL problems.

Other issues

Linking to a cloned site

Creating an application link between a site and its clone (a Jira site exported from the source site and then imported onto a second site) is not supported.

Workarounds:



DescriptionThis is part of our guide on Application Links Troubleshooting
ProductJira, Confluence, Bamboo, Fisheye, Crucible, Bitbucket
PlatformServer
Last modified on Oct 11, 2018

Was this helpful?

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