Application Links Troubleshooting Guide
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.
server.xmlfile were overwritten. Custom changes can include reverse proxy configuration and HTTPS configuration. You should check that the upgraded
server.xmlfile matches the pre-upgrade
The location of your
server.xml file depends on your application, operating system, and installation location.
Common default installation locations for Atlassian applications are:
Locations in Atlassian application's folder structure:
|Crucible||As for Fisheye.|
|Fisheye||The Fisheye configuration file is |
|Bitbucket Server 5.0|
N/A, replaced by
Please read through Migrate server.xml customizations to bitbucket.properties
|Bitbucket Server 4.0 – 4.14|
|Stash 3.8 – 3.11|
If you are on any of these later releases but your
We recommend that you copy
|Stash 3.7 and earlier|
<install-path> refers to where the application was installed on your system.
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.
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 server, enter 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:
- In the local application, go to Administration > Application Links and make sure there is an application link entry for your remote application.
- 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.
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.
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:
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.
- In the local application, click Administration > Application Links.
- Click Edit for the application link. Check the OAuth setup on the Incoming Authentication and Outgoing Authentication tabs for your application link.
- In the remote application, click Administration > Application Links.
- 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.
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:
- In the application that's prompting users to authenticate, change the Outgoing configuration setting for the application link to allow 2-Legged OAuth authentication.
- 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.
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.
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.
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.
|Logging configuration||Application logs||Tomcat webserver logs|
|Bitbucket Server / Stash|
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:
Recreating the link ensures that the application link uses any configuration changes you've made while troublshooting 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.
Delete an existing link
See Delete an application link for instructions.
Create a new link
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:
- The remote application is down
- The remote application is not responding
- A firewall is blocking requests
- Network request timed out
- Unable to locate the remote application
- Network response timed out
- Unable to reach the remote application
Follow the links above for diagnostics and specific actions you can take to resolve these connection problems.
The 'Configure Application Links' screen in Atlassian products provides diagnostics for the following OAuth problems that can occur with application links:
- Unrecognized OAuth consumer key
- OAuth signature rejected
- The system clocks are not synchronized
- OAuth mismatch
- Unsupported OAuth level
Follow the links above for diagnostics and specific actions you can take to resolve these OAuth problems.
The 'Configure Application Links' screen in Atlassian products provides diagnostics for the following SSL problems that can occur with application links:
- The remote certificate can't be trusted
- The remote certificate doesn't match the remote host name
- Unable to verify remote certificate details
Follow the links above for diagnostics and specific actions you can take to resolve these SSL problems.