Managing LexoRank

LexoRank is ranking system that Jira Software uses which provides the ability to rank issues in Jira Software instances. The user interface can be found in  > System > Lexorank management. It provides a user interface for several of the key areas of LexoRank administration.


As per the screenshot above, the UI provides the user with details on the distribution of issues in each bucket, and whether or not a balance is in progress or if it's disabled. Running a balance is similar to running a re-index of Jira, there isn't any guarantee it'll fix a problem unless the problem is specific to the ranking data.

The Rank Status column provides details about the status of the ranked issues. Each issue has a unique rank relative to the issues around it. This rank is stored as a string. As the amount of issues grows and you perform more ranking operations, the length of these strings increase. At some point, the length reaches a threshold, and a rebalance is scheduled within the next 12 hours.

A rebalance will evenly distribute the ranked issues, and significantly reduce the rank length. During a rebalance, ranking operations can continue as normal.

Should the length reach a second threshold within 12 hours, an immediate rebalance is started.

Should the length reach a third threshold before rebalance is finished, all rank operations are disabled until the rebalance completes.

The Rank Status field has these properties:

PropertyPossible values
  • OK - the rank length is in a healthy state
  • Warning - a rebalance has been scheduled
  • Critical - an immediate rebalance has started, you are approaching a state where rank operations will be disabled

<current length> / <maximum length>

Maximum length indicates when rank operations will be disabled

Next rebalance
  • Scheduled - once the next threshold is reached, a rebalance will be scheduled
  • Immediate - once the next threshold is reached, a rebalance will start immediately

In addition to the above, the field will tell you which project has the issues with the longest rank. This can be useful to diagnose the cause of a rapid increase in rank length.

If you're encountering issues and don't know why, or are unsure whether or not to balance, review the integrity checks first and contact support if need be as per the below details.

A breakdown of the service status is below:

Balancing disabled

If this is true then Jira Software has disabled balancing internally:

  • A foreground re-index may be running. It is expected that this will disable balancing.
  • Jira Software may have just been installed / upgraded and requires a reindex.
  • Check the logs for any exceptions and see if there are existing KB articles for these errors.
  • See if there is anything failing in the Integrity checks.
Balancing suspended
  • This will be false unless balancing has been explicitly suspended by Support or an administrator.
Balance handler running
  • This will be false unless a balance is currently in progress. To verify the progress of the balance, hit the refresh button.
  • On a Jira Data Center cluster this will be true on the node that is running the balance, and false on the other nodes.
Balancing in progress on a node of the cluster
  • It indicates that the balance cluster lock has been taken.
  • This will be true when a balance is running.

Integrity checks

This runs a series of tests against the LexoRank data and returns a true / false result based on the test. The tests are detailed below.

CheckHow to Fix Failures
Marker rows present in table for rank field.

If this fails, the minimum or maximum marker rows are missing.

Marker rows correctness check.

If this fails, the minimum or maximum marker rows exist, however they have the incorrect rank.

This can be fixed by updating the rank on the row returned in the check to be the expected value.

Marker rows in valid bucket check.

When a balance is in progress, the marker rows are moved to another bucket to indicate where the new rank values should be. The only time they should be is in different buckets is if a balance is in progress.

Valid states for the marker rows are the below.

  • Minimum is the same as maximum.
  • Minimum is 0, and max is 1.
  • Minimum is 1, and max is 2.
  • Minimum is 0, and max is 2.

This test fails if the marker rows are not in those buckets, and is likely caused by exceptions thrown during the rank creation or balance operation. Please check the logs for those and verify them against known problems.

Rank out of bounds check.Please refer to our How to Fix Rank Out Bound Error KB article for the fix.
Duplicate ranks check.This can be fixed as detailed in How To Fix Duplicate Rank Values For a Rank Field.
Issue ranks different from marker ranks check.

The below SQL will identify records that have ranking values the same as the min/marker rows. Deleting these records will correct this problem (and also result in a loss of ranking data for those issues only).

SELECT * FROM "AO_60DB71_LEXORANK" WHERE ("RANK" LIKE '%|zzzzzz:' OR "RANK" LIKE '%|000000:') AND "TYPE" not in (0,2);

(info) This may require changing depending upon the DBMS used.

Issue rows in valid bucket check.If a balance can't fix this, it would need detailed analysis from Atlassian Support.
Balance status check.Attempt a balance, and check the logs to see if there are any exceptions. It's likely the balance is failing due to a exception in the logs, or one of the other checks above may be failing.

If you're unsure how to proceed, please feel free to contact support for further assistance.

Last modified on Dec 10, 2019

Was this helpful?

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