JXL Documentation

# Troubleshooting

The JXL app experience is built on the shoulders of various Atlassian platforms. Sometimes the underlying Jira or Atlassian Marketplace (opens new window) systems and services can cause unexpected outcomes. Here's a list of things that can (rarely) happen and how to respond to them.

# Installation fails in Jira Cloud

If the installation is taking a long time and ends in Jira showing an indefinite error message, this can have a number of reasons that Atlassian refuses to indicate better in their error message. The most common ones are the following.

You might have an open quote with Atlassian. If you're paying Atlassian annually via quotes and your account is in arrears, Atlassian might not allow you to install some/any apps.

Atlassian might not have a valid payment method from you. Either you have no payment method provided or it's expired. Even though the JXL trial is (and even your Jira trial or plan might be) free, Atlassian might require a valid payment method to be on file in order to start trials of third-party apps.

  • Open the Jira settings menu in the navigation header bar and choose Billing.
  • On the Billing preview page, locate the relevant Jira product and click its Manage link.
  • On the Manage subscriptions page, if you see a warning message about your payment details, click the Add payment details link and follow the steps there.
  • Try to install JXL again.

You might have an existing, suspended subscription of JXL. Did you already have a trial of JXL, then uninstalled and reinstalled the app?

  • Open the Jira settings menu in the navigation header bar and choose Billing.
  • On the Billing preview page, locate the relevant Jira product and click its Manage link.
  • On the Manage subscriptions page, scroll down and look for an Inactive subscriptions section. If JXL is listed there, you need to contact Atlassian Support (opens new window) about this, using the link provided there.

Something has actually gone wrong during the installation of the app. This is very unlikely.

  • Visit the JXL Status (opens new window) site and check if Atlassian Jira app installation is operational.
  • If not, wait for Atlassian to fix their systems and try to install JXL again.

You can help

If you also think this indefinite error message is confusing and poor user experience, please help us by upvoting and commenting on the Atlassian issue that causes this. Visit UPM-6047 (opens new window), sign in with your usual Atlassian account, and click the Vote for this issue button at the top right of the page.

# Can't buy JXL for Jira Data Center

If you are trying to purchase JXL from My Atlassian (e.g. by clicking the Buy now button in the Universal Plugin Manager (opens new window)) and see an error message (along the lines of "We are unable to add the plugin to your cart. The plugin key is invalid.") this is caused by an Atlassian bug.

Please try purchasing through the Atlassian.com order form (opens new window) instead.

# Sheets not in Jira navigation right after installation

The Sheets item in the navigation is only visible if you have been granted the JXL: View sheets Permission, which should happen for all Users by default. However, sometimes something goes wrong on the Jira side when registering the Global permissions during the installation of the JXL app. This is caused by a known bug that Atlassian seems to refuse to track publicly or properly fix.

To resolve this, make sure you and all other relevant Users in your Jira site have this Permission, and ideally also the other JXL Permissions JXL: Edit sheets and JXL: Make bulk changes in sheets.

You can help

If you also think this is poor user experience, please help us by upvoting and commenting on the Atlassian bug that causes this. Visit ECO-63 (opens new window), sign in, and click the This affects my team link at the top right of the page.

# Can't find Sheets in the navigation in Jira Cloud

The navigation experience introduced by Atlassian (opens new window) in the beginning of 2025 fundamentally changes how you can use Jira. Instead of in a sidebar, you now find the Sheets item initially hidden in the More menu on the right of the horizontal tab navigation of each project.

Users who have Administer Jira or Administer Projects Permission (or in Team-managed projects in Jira Cloud the Administrator role), can customize the project navigation to bring the Sheets tab into direct view. Atlassian provides guidance on this here (opens new window).

In the Projects section of the sidebar navigation, under each Software Project, you need to choose a Board before being able to navigate to the Sheets in your Project. We are aware that this is nonsensical and a common cause for confusion, as your Sheets' scopes are unrelated to your Boards. Unfortunately, there is nothing we can do to fix this within the constraints we are working in. You need to first choose any arbitrary Board in the Project, then navigate to Sheets.

For improvement requests we recommend submitting feedback directly to Atlassian, as it's infeasible for us to control this part of your Jira experience.

# Can't find Sheets in Product discovery projects

For some reason, Atlassian has not (yet?) allowed any third-party app vendors to add items to the Product discovery project sidebar, which is a common source of confusion. As a workaround, you can create Sheets in other Project types and define a Sheet scope that captures your Jira Product Discovery Issues.

# JXL pages generally not loading

If instead of the JXL pages you see a blank screen or some unexpected code, check if you have any browser extension enabled that might cause this. Common examples include ad blocking solutions and tools that intercept requests and responses to display formatted code. Disable all such extensions and try again. If you identify any software that interferes in an unexpected way, please contact us (opens new window) so we can try to assist the relevant vendors in improving their products.

# Error 'Couldn't create/save sheet' in Jira Data Center

This can happen when your system is not currently connected to the internet.

Assuming the connection is stable, if you just installed JXL, it might also be a very rare case of a known Jira API bug related to the format of project keys. If your Jira system uses project keys that start with a number, which is a format not fully supported by Atlassian, some Jira APIs might fail to work as expected.

To compensate this Jira bug and prevent these errors in JXL, we have developed an alternative mode of exchanging data with the affected Jira APIs. You can switch to it by adding and enabling the Dark feature app.jxl.load-sheets-with-project-key in your Jira site (How to manage dark features (opens new window)).

Only do this if you are affected by this bug and it's not an option for you to adjust your project key format back to the standard pattern in Jira (Changing the project key format (opens new window)). Additionally, please contact us (opens new window) to let us know if you are using the Dark feature permanently.

You can help

If you also think this is poor user experience, please help us by upvoting and commenting on the Atlassian bug that causes this. Visit JSWSERVER-21574 (opens new window), sign in, and click the This affects my team link at the top right of the page.

# Sheet loads slowly

JXL offers consistent speed and overall performance at any scale. Even with a scope of tens of thousands of Issues, your Sheets should load within a few seconds or faster. Usually, when a Sheet loads slowly (more than 10 s), it's caused by a third-party app's Function in the JQL statement of its Sheet scope (a common example is issuesInEpics() from ScriptRunner (opens new window)).

There is no perfect solution to this, as we have no influence on the performance of Jira or other apps. Check if you really need to use Functions that cause slowness. As an example, the results of above-mentioned issuesInEpics() can often also be achieved using Structures, Level-specific search and filtering and Level filtering in JXL.

# Sheet loads 10,000 issues but more are needed

The issue loading limit is set to avoid running into request caps of the Jira API. Atlassian keeps tightening these limitations. JXL generally easily scales well beyond the initially configured 10,000 Issues, and this limit can be increased.

If you are using JXL for Jira Cloud, please contact us (opens new window) to get it adjusted.

If you are using JXL for Jira Data Center, you may increase and decrease the issue loading limit yourself. Add and enable the Dark feature app.jxl.issue-limit.{AMOUNT}, where {AMOUNT} is the number of issues you want to allow (How to manage dark features (opens new window)). Disclaimer: If this limit is increased, we cannot guarantee that the app always works and performs in the way you are used to because the rate at which it can retrieve data from Jira depends on how you host and configure your Jira instance’s infrastructure. While JXL uses sophisticated request orchestration, in extreme cases this could affect reliability of your Jira instance for all users.

# Issue dialog broken for issues of Product discovery projects

The Jira issue dialog is not capable of properly displaying most of the Field types introduced by Jira Product Discovery. For some reason, Atlassian has not (yet?) considered this to be a defect worth fixing, which is a common source of disappointment. Unfortunately, there's nothing we can do to improve this. We recommend opening these Issues in a new browser tab by holding down ⌘ Cmd (macOS) or ⌃ Ctrl (Windows, Linux, etc.) while clicking on the Issue key cell.

# Can't find some issue in sheet

If you are expecting a specific Issue to be listed in your Sheet but you can't find it, there are a few aspects that could cause this.

To start with, make sure that the Issue is indeed captured by the Sheet scope you have defined. If you need help writing or understanding a query, check Atlassian's JQL reference (Jira Query Language (opens new window)).

Once confirmed that the Issue is included in your Sheet's scope, make sure that there is no Column filtering enabled that could prevent the relevant Issue from being visible. Keep in mind that you could have filtering applied to multiple columns and any of them could be responsible for hiding the Issue. To check and clear all column filtering at once, click the highlighted icon in the status bar below the table and choose Reset column filtering. If the icon isn't highlighted, no column filtering is enabled.

Also check any Level filtering preferences you might have set that could prevent the relevant Issue from being visible. To reset this to its default state, click the icon above the row handles and click Reset, or click the highlighted icon in the status bar below the table and choose Reset level filtering. If the icon isn't highlighted, no level filtering preference is set.

Also check if you have typed anything in the Table search field that could prevent the relevant Issue from being visible. To clear the table search, empty the search field or click the highlighted icon in the status bar below the table and choose Clear table search. If the icon isn't highlighted, no table search is active.

# Can't update some field in sheets

While you can add any column to any Sheet in JXL, many table cells will only be available and editable for individual Issue types if you have configured Jira accordingly.

You need to have the appropriate Field added to the Issue type’s Screen in your Jira settings, specifically to the Edit operation Screen, or in absence of that to the Default Screen (Manage issue screens (opens new window)). The Field must also not be hidden in Field configurations. In Team-managed projects in Jira Cloud, the Field has to be added to the Issue type in Project settings (Customize an issue type's fields (opens new window)).

Generally, in order to be permitted to edit Fields of an Issue while it’s on a particular Status, its Workflow properties need to allow for it (Use workflow properties (opens new window)).

# Can't update Assignee field in sheets

If you edit a cell of an Assignee column, the Field appears to have been updated successfully, but then you realise it has not actually been updated, this is caused by a known bug in the Jira API.

You need to have the Assignee Field added to the Issue type’s Screen in your Jira settings, specifically to the Edit operation Screen, or in absence of that to the Default Screen (Manage issue screens (opens new window)). The Field must also not be hidden in Field configurations. In Team-managed projects in Jira Cloud, the Field has to be added to the Issue type in Project settings (Customize an issue type's fields (opens new window)).

If you have not added the Assignee Field to the relevant Screen, the Jira API should respond with an error. However, it returns a success response even though the update silently failed. This severe bug has been raised with Atlassian, but they have stated that they don't intend to fix it.

You can help

If you also think this is poor user experience, please help us by upvoting and commenting on the Atlassian bug that causes this. Visit JRACLOUD-81267 (opens new window), sign in with your usual Atlassian account, and click the This affects my team link at the top right of the page.

# Can't update time tracking fields in sheets

Jira only permits external apps like JXL to edit Fields if they are added to the relevant Screen. You need to have Time tracking added to the Issue type’s Screen in your Jira settings, specifically to the Edit operation Screen, or in absence of that to the Default Screen (Manage issue screens (opens new window)).

Adding this to the Screen/s can be an unexpected experience, as the necessary item to add is not named after the affected Fields (i.e. Original estimate, Time spent, Remaining estimate) but it's named Time tracking.

# Can't add some field's column to sheets

JXL supports a wide variety of Fields as table columns, including all Jira Standard fields, all your Custom field types, as well as many third-party apps' Fields (Supported fields).

If you come across a Field that's missing or that you think should work differently, feel free to let us know (opens new window) and we'll look into it.

# Columns with Builds information incorrectly empty in Jira Cloud

If some or all of the Builds status or Number of builds columns' cells are erroneously empty, this is caused by a known Jira bug.

You can help

If you also think this is poor user experience, please help us by upvoting and commenting on the Atlassian bug that causes this. Visit JSWCLOUD-23831 (opens new window), sign in with your usual Atlassian account, and click the This affects my team link at the top right of the page.

# Images not displayed correctly in Jira Cloud

A common cause for images failing to load is a flaky network connection.

However, if you uploaded custom Issue type icons, Priority icons, User avatars, Project avatars, Asset Object type avatars, image attachments, etc. in Jira and they are not displayed or replaced by grey shapes in JXL, this could also be because Atlassian is not properly handling third-party cookies (Chrome, Edge), also known as cross-site cookies (Safari, Firefox). If those are blocked, custom images often can't be displayed in third-party apps like JXL.

The only known solution to this is to allow third-party cookies (opens new window) in your browser or add a specific exception for [*.]atlassian.net in your browser's cookies settings.

# More

If the hints above didn't help, contact us (opens new window).

Updated: 6 May 2025

← Frequently asked questions →

© Appfire