When attempting a zero down time upgrade, Jira will not start noting that 'Jira does not support zero downtime upgrades between major releases'

Summary

While attempting to perform a zero-downtime upgrade for Jira Data Center between major version releases (for example, Jira 8 to Jira 9), any upgraded node cannot restart as part of the cluster.

Environment

Jira Data Center 7.3 and higher

Diagnosis

• The following message is shown in the atlassian-jira.log when attempting to start the node:

  Unable to start JIRA. java.lang.illegalStateException: Your node with Jira version 9.2.0 will not start up with version 8.22.2 because Jira does not support zero downtime upgrades between major releases.

  ⚠️ Version numbers in the message may differ.

• Running the database query SELECT * FROM clusterupgradestate will show the value READY_TO_UPGRADE for the field state as the last row.

  Example

  SELECT * FROM clusterupgradestate; id database_time cluster_build_number cluster_version state order_number 10000 1750956567766 940030 9.4.30 READY_TO_UPGRADE 1 10100 1750956899466 940030 9.4.30 MIXED 2 10001 1750956938541 940030 9.4.30 READY_TO_RUN_UPGRADE_TASKS 3 10101 1750957209135 940030 9.4.30 RUNNING_UPGRADE_TASKS 4 10200 1750957209937 9120024 9.12.24 STABLE 5 10201 1750957281745 9120024 9.12.24 READY_TO_UPGRADE 6

  ℹ️ Note the field order_number!

• A single upgraded node can be started by disabling clustering by removing the cluster.properties files from the Jira Home directory for that node.

Cause

A zero-downtime upgrade can't be performed between major version releases, for example, Jira 8 to Jira 9. Zero downtime upgrades can only be performed when upgrading within a major version, such as Jira 8.13.2 to Jira 8.20.11.

Solution

In order to restore the clustering functionality, the instance will need to be taken out of upgrade mode and then upgraded with downtime.

Recommended option

• Stop all nodes.

• If all your nodes are already upgraded, downgrade one of the nodes to the previous version.

  • Prior to starting the older version of the software, you will need to add the following JVM argument.

    -Djira.downgrade.allowed=true

  • Setting properties and options on startup provides additional details on adding JVM arguments.

• Start up only this node in cluster mode (with the cluster.properties file in the Jira Home location).

• Disable upgrade mode via Settings > Applications > Jira Upgrades > Cancel Upgrade.

• Stop the downgraded node.

• Start one of the upgraded nodes in cluster mode and ensure the system is upgraded and accessible from this node.

• If it is accessible from the upgraded node, upgrade and start all remaining nodes.

Alternative option (DB manipulation)

• Stop all nodes.

• For minimal impact, only remove the last row from the clusterupgradestate table. Identify the highest number in the field order_number by running the following query

  SELECT * FROM clusterupgradestate;

• Run the following database query to remove the upgrade mode:

  DELETE FROM clusterupgradestate WHERE order_number = <order_number>;

  Replace <order_number> with the highest number from your table. For the earlier example, this would be 6.

• Start one of the upgraded nodes in cluster mode and ensure the system is upgraded and accessible from this node.

• If it is accessible from the upgraded node, upgrade and start all remaining nodes.