JIRA 4.0 Upgrade Guide

On this page:

Before You Upgrade

Please note the following points before starting your upgrade:

  • Problems running JIRA 4.0 with WebLogic — We are currently aware of an issue that is preventing JIRA 4.0 from running on WebLogic. If you are currently using JIRA with WebLogic, we strongly recommend that you do not upgrade JIRA until a fix is available. You can track the progress of this issue here: JRA-19367
  • Problems running JIRA 4.0 with IBM JVM and JRocket JVM — We recommend that you use the Sun JVM with JIRA 4.0. We are currently aware of issues preventing JIRA 4.0 from working with the IBM JVM and JRocket JVM. You can track the progress of these issues here:
  • Problems using the JIRA Portlet Macro in Confluence 3.0.x with JIRA 4.0, please read JIRA Portlet Macro page in the Confluence documentation for further information.
  • If you are upgrading from JIRA 3.12 or earlier, please read the 'Upgrading from JIRA 3.12 and earlier' section below before starting your upgrade.

Tomcat, Apache and mod_proxy setup

Unlike previous versions of JIRA, the new JIRA 4 Dashboard frequently makes HTTP requests to itself. For this reason, the hostname, port and protocol (http/https) must be correct throughout all portions of the request chain. Additionally, if you are using SSL, JIRA's JVM must be able to trust the SSL certificate on a JIRA response. If your setup is not configured correctly, the Dashboard in JIRA will not work. Please read this knowledge base article if you are having problems.

Upgrading from JIRA 3.13.x to 4.0

Licensing Changes

JIRA 4.0 introduces some significant licensing changes. Before you begin the upgrade, please go to my.atlassian.com for your upgraded license. Please note, any existing 3.x license files will not work with 4.0.

JIRA has moved to a user-based licensing model in JIRA 4.0. This means that you will need to calculate the number of users in your JIRA system to determine what license you will need, before you can complete your upgrade. For more information on this, please see the JIRA pricing changes FAQ.

Once you have upgraded your license, please follow the instructions below:

General Upgrade Instructions

Please ensure that you follow the instructions in the general JIRA upgrade guide (non-version specific), as well as the JIRA 4.0 specific instructions in the sections below. The general upgrade guide contains important tasks that are essential for getting your upgraded JIRA instance to work correctly (e.g. merging jira-application.properties customisations from the old instance to the upgraded instance).

Scheduling the Upgrade

Please note that upgrading to JIRA 4.0 may take a long time, depending on the size of your instance as well as server and database performance. During the upgrade, several upgrade tasks will need to run to upgrade your data to be ready for JIRA 4.0, such as:

  • Calculating a resolution date for all resolved issues in your system
  • Re-indexing your issues
  • Converting saved filters to use JQL
  • Converting existing portlets to gadgets

Please schedule sufficient downtime time for the upgrade in your production environment. It is recommended to run an upgrade first in a test environment to see how long the upgrade will take for your data set and hardware configuration.

Java Version

If you are running JIRA under version 6 (1.6) of the Sun JRE, please ensure that you are running a point release JRE 6 (1.6) Update 10 or higher. The reasons for this are:

  • JIRA 4.0 introduces a new REST plugin type based on Jersey, which will not work with JRE 6 - JRE 6 Update 3. If you are running JIRA with one of these versions of the JRE you will see the following errors:
    java.lang.LinkageError: JAXB 2.0 API is being loaded from the bootstrap classloader,
    but this RI (from bundle://16.0:3/com/sun/xml/bind/v2/model/impl/ModelBuilder.class)
    needs 2.1 API. Use the endorsed directory mechanism to place jaxb-api.jar in the bootstrap
    classloader. (See http://java.sun.com/j2se/1.5.0/docs/guide/standards/)
    Note: JRE 5 (1.5) doesn't have this problem since it doesn't bundle JAXB.
  • JIRA 4.0 uses Lucene v2.3, which is affected by a Sun hotspot compiler bug in JRE 6 (1.6) Update 4 and upwards (see JRA-15681). The bug is fixed in JRE 6 (1.6) Update10.


JIRA 4.0 has a new directory structure — for details, please see Important Directories and Files.

Please ensure that you set the jira.home property as described here.

Recommended Browsers

The following browsers are recommended for use with JIRA 4:

  • Internet Explorer 7 and 8
  • Firefox 3.x
  • Safari 4

(tick) Tip: If you are looking for our recommended databases and applications servers, you can find them here:

Users May Encounter 'Advanced Search'

If any of your users have saved invalid filters, the new 'Advanced Search' screen may appear when they try to display them.

'mail.mime.decodeparameters' System Property

The following system property must be set in order for the JIRA mail handler to work correctly with emails from RFC 2231-compliant mail clients:

Refer to Setting Properties and Options on Startup for instructions.

'Resolution Date' System Field

JIRA 4.0 introduces a new system field, the Resolution Date. This field provides the date when an issue last entered into a 'Resolved' workflow state. When upgrading to JIRA 4.0, an upgrade task will run, calculating the Resolution Date for every resolved issue in your system. If you have a large number of issues, this may take a long time. The speed at which this upgrade task runs can be improved by ensuring that your database statistics are up to date for your changegroup and changeitem tables (to ensure the database will select the most effective query plan).

For example, on Postgres this can be done by executing the following commands:

jiratest=# ANALYZE changegroup;
jiratest=# ANALYZE changeitem;

JIRA's RPC interface now provides two new methods to retrieve an issue's Resolution Date:

The RemoteIssue class was left unchanged, to ensure backwards compatibility of RPC clients.

Database Schema Changes

If you are using an Oracle or MySQL database, please note that two column data types have been changed.

Therefore, the easiest way to upgrade to JIRA 4.0 is to perform an XML backup and restore as described in the Migrating JIRA to Another Server instructions.

If in the past, instead of performing an XML backup and restore, you have been upgrading by "pointing" the new version of JIRA at an old database, this is still possible. However, the procedure is more complicated. You will need to use SQL scripts to perform database schema changes.

For details (and the scripts), please see JIRA 4.0 Database Schema Changes for MySQL and Oracle .

Charting Plugin

JIRA 4.0 now bundles most of the charts previously provided by the JIRA charting plugin. If you currently have the JIRA charting plugin installed (v1.4.1 or previous) in  WEB-INF/lib, please remove it as otherwise JIRA will fail to start.

The following charts have not been bundled with JIRA 4.0. If you are using any of the following charts, you will need to upgrade to version 1.5 of the JIRA charting plugin:

  • Time to First Response Chart
  • Average Number of Times in Status Chart
  • Average Time in Status Chart
  • Workload Pie Chart Report

JIRA Toolkit

If you are using the JIRA Toolkit, you will need to upgrade it to the latest version.

You will also need to install it in your JIRA home directory, rather than your atlassian-jira/WEB-INF/lib/ directory as it now runs in an OSGi container. Read Managing Add-ons for more information.

GreenHopper Plugin

GreenHopper for JIRA 4.0 is now available for use with JIRA 4.0. You can download it on the GreenHopper Plugin for JIRA Downloads page. Please follow the GreenHopper Installation and Upgrade Guide for instructions on how to upgrade GreenHopper.

Please note, you need to upgrade your GreenHopper license before you can use GreenHopper with JIRA 4.0. Any existing GreenHopper license files will not work with JIRA 4.0. You can obtain a license from http://my.atlassian.com.

Issue 'Status' Field Problem

Prior to JIRA 4.0, it was possible to create two statuses whose names differed only in case (e.g. 'Resolved' and 'RESOLVED'). If you upgrade to JIRA 4.0, this will lead to ambiguities. Consider this scenario:

  1. You have defined two issue statuses in a project with names that differ only in case, ('In Progress (Services)' and 'IN PROGRESS (SERVICES)'), to use in different workflows.
  2. At a point in time, 100 issues are assigned the first status of 'In Progress (Services)' and 50 issues are assigned the second status of 'IN PROGRESS (SERVICES)'.
  3. You browse the project's issues. The 'Status Summary' will incorrectly show only one 'In Progress (Services)' status with either 100 or 50 issues (picked randomly). The issue totals in the other summaries (By Priority, etc) will also be incorrect, due to JIRA not recognising the statuses as distinct.

Additionally, you will receive ambiguous results if you attempt to perform a search by name on the status in the Advanced Search (e.g. "Status = In Progress (Services)").

To resolve this issue, we recommend that you ensure that each issue status is distinct by renaming the duplicate statuses appropriately. You may also need to update any issue filters that you have set up.

Plugin Notes

JIRA 4.0 introduces several changes that may break existing plugins.

There are now two different types of plugins. Each type of plugin needs to be installed into a different directory to work. Read Managing Add-ons for more information.

If you are using a plugin that is not shipped with JIRA, the plugin may need to be updated to work with JIRA 4.0. If the plugin was written by you, please read through Updating JIRA Plugins for JIRA 4.0 and see if any of it is relevant to your plugin. If you are using a plugin written by a third party, please check with the plugin's author to see if the plugin has been tested with JIRA 4.0.


Running JIRA v4.0 may require more RAM than running v3.x.
The default settings (suitable for small to medium usage) for standalone allocates a total of 512MB memory to the JIRA application.
Please ensure your server has enough available RAM to cover this.
If you are installing JIRA as a WAR/EAR, then you may need to increase the amount of "PermGen" memory allocated to JIRA. 256MB PermGen is recommended.

Upgrading from JIRA 3.12 and earlier

In addition to the points listed above, please read the Upgrade Guide for every version you are skipping during the upgrade. The complete list of Upgrade Guides is available here.

Please also note the following:

Upgrading from JIRA 2.x Data and earlier

If you are upgrading from JIRA 2.x data (or earlier) to JIRA 4.0, you must upgrade to any JIRA 3.x release first (3.13.5 recommended). You can then follow the JIRA 4.0 Upgrade Guide to upgrade your JIRA instance to 4.0.
Last modified on Apr 14, 2011

Was this helpful?

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