JIRA is now available as three separate applications, JIRA Software, JIRA Service Desk, and JIRA Core. For more information on administering these applications, refer to the Administering JIRA Applications documentation.

Restoring Data

This process is typically conducted towards the end of Migrating JIRA to Another Server or splitting your JIRA instance across multiple servers.

If you wish restore a single project from your backup into an existing JIRA instance, refer to these instructions on restoring a project from backup instead.

Restoring JIRA from backup is a three stage process:

  1. (Optional) Disable email sending/receiving
  2. Restore data from XML to the database
  3. (Optional) Restore the attachments to the attachments directory (if attachments were backed up)

On this page:

Before you begin

  • When restoring data, all data in the existing JIRA database is deleted, including all user accounts. Before you begin, make sure you have the password to a login in the backup file that has the JIRA System Administrator global permission.

  • If you are restoring data from a JIRA Cloud site to an installed JIRA server, please read Migrating from JIRA Cloud to JIRA Server.

1. Disabling email sending/receiving

If you are restoring production data into a test JIRA instance for experimentation purposes, you probably want to disable JIRA's email interaction features before you begin:

  • Disable email notifications — if JIRA is configured to send emails about changes to issues, and you want to make test modifications to the copy, you should start JIRA with the -Datlassian.mail.senddisabled=true flag.
  • Disable POP/IMAP email polling — if JIRA is configured to poll a mailbox (to create issues from mails), you will likely want to disable this polling on your test installation. This is done by setting the -Datlassian.mail.fetchdisabled=true flag.

Exactly how to set these flags is dependent on your particular application server, but for JIRA, this is done by setting the DISABLE_NOTIFICATIONS environment variable before starting JIRA (note, use startup.sh instead of startup.bat if you are not using Windows):

You could also try un-commenting the DISABLE_NOTIFICATIONS=" -Datlassian.mail.senddisabled=true -Datlassian.mail.fetchdisabled=true -Datlassian.mail.popdisabled=true" line from your /bin/setenv.bat file (/bin/setenv.sh if you are not using Windows) and then running startup.

2. Restoring XML data

(warning) These instructions assume that you are restoring JIRA data from an XML backup. If you used native database tools to back up your JIRA data, the restore process will be tool-specific and so these instructions (i.e. stage 2 of 3) do not apply to you.

  1. Log in as a user with the 'JIRA System Administrators' global permission.
  2. Choose > System. Select Import & Export > Restore System to open the Restore JIRA data from Backup page.
    (tick) Keyboard shortcut: 'g' + 'g' + type 'rest'
  3. In the 'File name' field, type the file name of the zipped XML backup file generated by JIRA.
    (info) Ensure that this backup file has been moved or copied to the location specified below this field.
  4. The Index Path field indicates where JIRA will restore the search index data from the zipped XML backup file. This location (which cannot be modified) matches the index path specified in the zipped XML backup file. If, however, this backup file does not specify an index path, JIRA will restore the search index to the caches/indexes subdirectory of the JIRA Home Directory.
    (warning) Please Note:
    • The contents of the index directory may be deleted by the restore process.
    • The index directory should only contain JIRA index data.
  5. Click the 'Restore' button and wait while your JIRA data is restored.
    (info) Once the data has been restored, JIRA will inform you that you have been logged out. This happens because all JIRA users which existed in JIRA prior to JIRA's data being restored will have been deleted and replaced by users stored in the JIRA export file.

(info) It is recommended that you avoid passing through a proxy when performing an XML restore, especially if your JIRA instance is very large. Using a proxy may cause timeout errors.

3. Restoring attachments

If you created a backup of the attachments directory, you will need to restore the backup into a directory where JIRA can access it.
(warning) If you use a custom directory for storing your attachments, ensure that JIRA has read and write permissions to this directory and its subdirectories.

The process of restoring the attachments backup depends on the way it was created. Usually you can use the same tool to restore the backup as the one that was used to create it (see Backing up attachments).

If you are restoring the attachments into a different location (i.e. a different directory path) from where they were previously located (e.g. this will be the case when moving servers), please follow the instructions provided in Configuring attachments to change the location of the attachments directory so that JIRA can find the restored attachments.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

25 Archived comments

  1. User avatar

    Matthew New

    Greetings Atlassian,

    If I use the standalone Windows installer to install JIRA and it is installed as a service, which file would I edit to disable email sending/receiving? I tried uncommenting the "DISABLE_NOTIFICATIONS" setting in bin\setenv.sh and it did not work.  


    Matthew New
    University of Michigan

    14 Mar 2011
    1. User avatar


      I guess you need to edit setenv.bat instead of setenv.sh in windows

      03 Aug 2011
  2. User avatar

    Adam Saint-Prix

    Hi Matthew,

    I think you probably want to look at this document on Setting Properties for Windows Services via the command Line or using the registry editor. The example given is for increasing memory, but you can substitute that option for the disable notifications flag: -Datlassian.mail.senddisabled=true.

    Also, as a general rule it's best to ask these types of questions in the 'Atlassian Answers' site (which you can access via the 'Get Answers' link/button at the end of this page). You are more likely to get a quicker response there and input from multiple community members on the off chance that the initial response is off the mark. (wink)

    Anyhow, hopefully this helps.

    14 Mar 2011
    1. User avatar

      Giles Gaskell

      You may also find some older information in our JIRA Forums site, although please be aware that this site has been superseded by 'Atlassian Answers' and that our 'JIRA Forums' site is now effectively 'read only'.

      23 Sep 2011
  3. User avatar

    Rambanam Prasad


    I am trying Restore data from XML file(backup taken from jira 4.0)  it is giving error as


    • Error parsing export file. Your export file is invalid. This may be due to a CDATA bug in older versions of JIRA (http://jira.atlassian.com/browse/JRA-4980). Exception is org.xml.sax.SAXParseException: Element type "Action" must be followed by either attribute specifications, ">" or "/>".

    can anyone help on this


    24 May 2011
  4. User avatar

    David Freitas

    Another point that is missed is: if you change your jira logo, it doesn't get restored when you move to a new instance.

    22 Sep 2011
    1. User avatar

      Omar Shehab

      This could be a feature request.

      19 Jun 2013
  5. User avatar

    Srinivas Marripudi

    Hi Guys,

    I imported prod xml backup into my local dev JIRA instance but I'm unable to login after restore. Exception which I try to access Jira login page:

    JIRA is unable to migrate the User Directory configuration because external users exist but the osuser.xml file is not available.
    Please see Upgrading JIRA for details.

    I'm not using LDAP User adminintration in my local dev env and that seems to be the issue here. I just wanted to import workflows, custom fields, schemes etc. for some development reasons & now I can't even login.

    Any ideas how I can get around this problem ? Thanks.

    30 Sep 2011
    1. User avatar


      Its a late reply but for sure it will help someone.

      If you have osuser.xml LDAP login with JIRA older that 4.3 you should copy osuser.xml to the new 5.x JIRA and then do the import.

      if you dont have osuser.xml before the import, you wont be able to login using LDAP.



      30 Jul 2012
  6. User avatar

    Lilly Auburger

    Restore test from XML file into a new Jira installation worked fine. But now I'm a little bit confused. As I've read, I should backup db (MySQL) with tools provided with this db. So, I have the following questions:

    • Why do I need a db backup, if I don't need/use it for recovery?
    • Can I restore Jira data by restoring MySQL db and .../data directory without any Jira XML file?
    • If not, in which order should I recover my data (fist XML, than db or vice versa)?

    Thanks for clearing this puzzlement.

    12 Oct 2011
    1. User avatar

      Justin Rand

      I believe the DB dump is the recommended method as the XML backups can become corrupted/inconsistent fairly easily.

      You should restore your data by restoring the MySQL db and the data directory without the xml file or vice versa. Importing an XML file will erase the existing JIRA DB anyway, so you'd be duplicating effort if you did both.

      One thing to note, if you are migrating from one server to another is to modify the Base URL (JIRA Administration->General Configuration) to your new URL. I just loaded our JIRA instance onto a new server and all of the "Activity Stream" links pointed to the old server until I updated the Base URL value.

      19 Oct 2011
      1. User avatar

        John Dzilvelis

        Also, if you are refreshing your development instance by restoring the MySQL database, Run the "re-index" feature, under "system -> Advanced -> Indexing" .


        It appears that issues are cached, perhaps in JIRA_home, and they cause exception.

        27 Oct 2011
  7. User avatar



    I am about to start importing a backup created (by Support) from a JIRA Studio installation to a local installation of JIRA. Reading this document does raise some questions:

    • I see that the XML files define the database name ("PostgreSQL") and database type (also PostgreSQL). Now our local installation is using MySQL. Will this work?
    • We already configured JIRA to use CROWD as SSO service. It is configured with the default "read-only" mode. Will this be a problem with the restore?


    19 Oct 2011
  8. User avatar



    I'm trying to import the Test Case Management Sample .zip from documentation:

    JIRA Sample File - Test Case Management (click on Sample file link to download sample).

    but I get the following error:

    Error importing data: org.xml.sax.SAXException: The XML document does not contain the <entity-engine-xml> root element or it was closed too early.

    I'm using version 4.2 and I believe the sample was created with 3.x.

    Is there any way to get around this problem?



    19 Apr 2012
  9. User avatar


    I am moving from an OnDemand instance to a local server JIRA.  When I attempt to restore my xml file to my server JIRA i get a "The xml data you are trying to import seems to be from a newer version of JIRA. This will not work." error.  What is the work around?

    11 Oct 2012
    1. User avatar

      Andrew Lui [Atlassian Technical Writer]


      The version of your local JIRA server needs to "match" the current JIRA OnDemand milestone version.

      You can find the current milestone version of JIRA OnDemand by navigating to Administration > Issues > System Info > JIRA Info. It should look something like this 5.2-m06. JIRA 5.2m1 is paired with 5.1.1, JIRA 5.2m2 is paired with 5.1.2, JIRA 5.2m3 is paired with 5.1.3, etc, so for a JIRA export from 5.2-m06, you will need to download and install JIRA 5.1.6.

      You can find more information about this on Migrating from JIRA OnDemand to a JIRA Installed Site. I'll note this in the instructions above.

      Kind Regards,

      11 Oct 2012
  10. User avatar

    David Finney

    I tried to follow the resources you provided. After resetting the database I reinstalled JIRA and in the Setup Wizard I choose Import Existing Data. It gave an error message: "Unable to find ActiveObjects plugin. The plugin must be enabled for the restore to work.". I didn't find any such plugin in the marketplace.

    03 Jul 2013
  11. User avatar



    I'm also moving from onDemand setup to local server JIRA.  I'm getting this error in restoring:

    'Error importing data: java.lang.IllegalArgumentException: [GenericDelegator.makeValue] could not find entity for entityName: MovedIssueKey'.  Do you have any idea what it is?

    17 Jul 2013
  12. User avatar


    In trying to attempt an xml restore I am running into an issue on the db (Oracle) side.  The prod tablespace I am restoring from shows as about 521mb, but when I try and do the restore the 2GB of free space is not enough and the db fills up.  Has anyone else run into this?  Seems the restore takes up way more space than the existing instance?

    08 Aug 2013
  13. User avatar

    Cool cool

    when i try to restore , it show  Invalid license key specified.

    how to do ?




    31 Mar 2014
  14. User avatar

    Vivek Siddhartha

    HI Guys,

     Getting below error while importing the data of OnDemand to in Premises JIRA.. 

    Error importing data: java.lang.IllegalArgumentException: [GenericEntity.set] "deltaTo" is not a field of 


    14 Apr 2014
  15. User avatar

    keshav kumar

    Hello experts,

    I have a requirement of showing capacity matrix for all the team members.

    can anybody help me with this.i need  a screen to display all this  below table details.

    thanks in advance

    Team member nameno of days availableno of hours / daytotal availbility
    01 Aug 2014
  16. User avatar

    James Rice

    Am I the only one who thinks it's a little odd that the backup puts the file in a different location than the restore AND you can't change the location of the restore file?

    30 Jan 2015
  17. User avatar


    Hi, I have a concern about this part:

    The Index Path field indicates where JIRA will restore the search index data from the zipped XML backup file. This location (which cannot be modified) matches the index path specified in the zipped XML backup file. If, however, this backup file does not specify an index path, JIRA will restore the search index to the caches/indexes subdirectory of the JIRA Home Directory.

    Since my new instance has access to the same file system, this means that it will overwrite the current index? How can I make sure that the index path is not specififed in the XML backup so it can be restored in the NEW JIRA home directory?


    Thank you!

    24 Jul 2015
  18. User avatar


    JIRA Agile should be installed before restoring data, details here: Backing Up and Restoring Data

    30 Jul 2015
Powered by Confluence and Scroll Viewport