Search indexing

In order to provide fast searching, JIRA creates an index of the text entered into issue fields. This index is stored on the file system, and updated whenever issue text is added or modified. It is sometimes necessary to regenerate this index manually; for instance if issues have been manually entered into the database, or the index has been lost or corrupted.

See Re-indexing after major configuration changes for more information on when you should re-index.

Note: For all of the following procedures, you must be logged in as a user with the  JIRA Administrators global permission.

Re-indexing JIRA

  1. Choose > System
  2. Select Advanced > Indexing to open the Indexing page.
  3. This page allows you to choose one of the following two re-indexing options:

    • Background re-index — This will re-index all issues in the background.
    • Lock JIRA and rebuild index — This will delete and rebuild all indexes, including the comment and change history indexes.

Screenshot: Re-indexing JIRA

Which re-indexing option should I use?

Background re-index

This option should be used in the majority of circumstances, particularly following changes to the configuration. It will generally take significantly longer to perform than the Lock JIRA and rebuild index option, but it allows JIRA to remain usable while it is being done. There will, however, be a performance impact on JIRA as a whole. We recommend that you perform this option during a low usage period. The actual impact of running the Background re-index option will depend upon the customer's particular hardware and software installation as well as how many issues are in the system.

Lock JIRA and rebuild index

This option should be used when the indexes are corrupted, which may be caused by a system or disk failure. It deletes all indexes and then rebuilds them, and is often called a "full reindex". This option is much faster than a background re-index. If you're using JIRA Server, you'll need to shut down JIRA while it's being done. For Data Center, you can perform the re-index with no downtime, which allows you to use this option more frequently.


The following table summarizes the differences between the two options:

Background re-index Lock JIRA and rebuild index
Single threaded. Slow to complete. Multithreaded. Fast to complete.

JIRA can be used by users during re-index.

JIRA Server can't be used by users during re-index, but you can work around it for JIRA Data Center.

Can be canceled at any time. Can't be canceled once started.

Keeps the current index, and updates it.

Deletes the current index, and rebuilds it.


Choosing a custom Index Path

  • If you upgraded JIRA with an XML backup from a JIRA version prior to 4.2 and used a custom directory for your index path, you can choose between using this custom directory (which cannot be edited) or the default directory for your index path location. However, once you switch to using the default directory, you can no longer choose the custom directory option.
  • The default directory location is the caches/indexes subdirectory of the JIRA application home directory.

(info) NFS storage for JIRA indexes is not supported. See Supported platforms for more information.

Re-indexing JIRA Data Center with no downtime

Keeping the integrity of indexes is as important as having your JIRA instance open to users all the time. These steps will help you run the Lock JIRA and rebuild index option, which deletes and recreates all indexes, with no downtime.

Before you begin:

Choose a node and remove it from the load balancer. You'll use it to perform the re-index.

To re-index JIRA Data Center with no downtime:

  1. Access JIRA on the node you've chosen, and select  > System.
  2. Select Advanced > Indexing to open the Indexing page. Then, run Lock JIRA and re-build index.
  3. After the re-indexing is complete, take a look around the JIRA instance to make sure everything looks fine.
  4. Add the node back to the load balancer.

After completing the re-indexing, the rebuilt indexes will be automatically distributed to other nodes in the cluster (there might be some performance degradation during that time). If some changes were made to the indexes in the meantime, they will also be applied to maintain the integrity.

Backing up and recovering your index

Enabling index recovery will cause a snapshot of the indexes to be taken periodically. This allows you to recover your index quickly, rather than rebuilding the index, if there is a failure. This is particularly useful if you have a large JIRA installation and you cannot afford for it to be offline for long. If you have a small JIRA instance, it may not be worth enabling index recovery, as rebuilding the index won't take much time.

Whether a full index rebuild is faster than recovering from a snapshot depends on a number of factors, including how recent the snapshot being recovered was taken. Large and complex installations should test this process on a development/testing server before relying on it in production.

To enable index recovery:

  1. Navigate to the Indexing page (as described above).
  2. Click Edit Settings to enable index recovery and choose the frequency of snapshots.
    • Snapshots are stored in the <yourjirahome>/exports/export/indexsnapshotsdirectory.

To recover an index:

  1. Navigate to the Indexing page (as described above).
  2. Enter the name of the previously saved index in File name and click Recover.
    • JIRA will not be available during the recovery of the index. 
    • If changes were made to the configuration that required a re-index after the snapshot was taken, then you will need to do a background re-index after the recovery. Note, JIRA will be available after the recovery.

Additional information

  • JIRA will retain the last three snapshots at any time (in <yourjirahome>/exports/export/indexsnapshots). Older snapshots will be automatically deleted. Note, snapshots may occupy considerable disk space and may need to be moved to offline storage or deleted as appropriate.
  • The snapshot process is a relatively lightweight process and does not place much of a load on the system.
  • The process of taking a snapshot will require temporary disk space equivalent to the index size. The resulting snapshots will each be about 25% the size of the index.
  • All issues will be re-indexed appropriately during the recovery, including issues that were added, updated or deleted after the snapshot was taken.
  • You can use the index recovery process to bring your index up to date, if you need to restore your JIRA database. The index snapshot must pre-date the database backup being restored.

Re-indexing a single project

If you have made a configuration change that affects a single project, you can re-index just that project. This option is the same as a background reindex, only limited to a single project. See Re-indexing after major configuration changes for more information on when you should re-index.

To re-index a single project:

  1. Navigate to the desired project and click the Administration tab.
  2. Click Actions > Re-index project to start re-indexing the project.


Last modified on Nov 10, 2017

Was this helpful?

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