Troubleshoot index problems in Jira server

Still need help?

The Atlassian Community is here for you.

Ask the community


The JIRA applications index controls searching and the activity stream, however it will also query the applications database (such as to retrieve change histories). Indexing in JIRA applications is performed by Lucene a high-performance, full-featured text search engine library.

What you need to know

JIRA applications will perform partial re-indexes of the Lucene index after every issue change, this is handled by the Issue Index Listener viewable in Administration > System > Listeners.

It is also possible to run a complete re-index on demand by running a manual re-index from Administration > System > Indexing. From this location you can also specify a new location for JIRA applications index files.

Indexing speed is not affected by Language Settings. Instead, it relies heavily by the I/O speed of the disk and this could be affected by Antivirus or Virtualised Environment.

Changing the indexing language however play a significant part in the word-stemming and searching.


Indexing recommendations

We really only have one major recommendation when it comes to indexing:

Golden Rule

The file path that you specify for JIRA applications indexes must be located on a fast local disk.

If JIRA is accessing its indexes across a network drive, Samba or NFS mount you are going to run into indexing exceptions, this would be a likely exception:

2006-03-28 13:06:05,540 ERROR [jira.issue.index.DefaultIndexManager] Giving up reindex - waited 10 seconds

So you should never run JIRA applications with this type of configuration.

Indexing errors

Locking Exception

This can occur when another process has a lock on the index, possible causes of this are:

  • There is a lock file left on disk from a previous unclean restart.
  • An old JIRA applications instance still has threads running; possibly from an earlier JIRA applications instance that was not entirely shut down when JIRA was last restarted.
  • A process from the current JIRA application instance that is taking an unusually long time (10+seconds) finishing.

If your logs mention a .lock file the safest solution is too:

  1. Stop your JIRA application
  2. Delete the .lock files
  3. Restart your JIRA application.
  4. Perform a full re-index.

These lock files (if you are running JIRA applications standalone) will be in Tomcat's temp directory. If you need some extra information finding these lock files it may help to have a quick read of the F.A.Q. article on the Lucene wiki.

Timeout Exceptions

Increase the index wait time

If you are seeing exceptions similar to the example above there may be some contention for the lucene indexes. The first option is to increase the allowable timeout for obtaining a lock.

This is done by modifying the file, specifically the value:

Take a thread dump

JIRA will automatically perform do a thread dump into the log file in the event of index lock timeouts. If the above does not work and you are still seeing these exceptions it is time to create a support request and attach a thread dump when this error is occurring. Hopefully this thread dump will show what JIRA is currently waiting on to grab the lock on the indexing files.

Poor Indexing Performance

If indexing performance is poor, the typical result is slow response times and index timeouts. Index timeouts will result in potentially out-of-date issue results from searches and in issue navigator and portlets.

Note that poor indexing performance is typically the result of poor disk performance. Note also that an overwhelmingly common cause of poor disk performance on MS Windows is anti-virus software. Understandably, many customers find it difficult to understand how many anti-virus products can continue to have a serious negative impact on disk performance even when the antivirus software is disabled. Nevertheless, it is sometimes necessary to completely uninstall anti-virus software in order to correctly assess the impact it has on disk performance and JIRA indexing. Many anti-virus products can exclude designated directories from close, performance degrading monitoring. The JIRA index directory would be an ideal candidate for such an exclusion.

You can use our disk access speed utility to determine if disk performance is a problem for you. Compare the results you get to our published Good results in that page.

Knowledge Base Articles

Check known searching, indexing, and filters issues from our Knowledge Base

Last modified on Sep 25, 2019

Was this helpful?

Provide feedback about this article

In this section

Powered by Confluence and Scroll Viewport.