Troubleshoot index problems in Jira server

Related content

  • No related content found

Still need help?

The Atlassian Community is here for you.

Ask the community

Platform notice: Server and Data Center only. This article only applies to Atlassian products on the Server and Data Center platforms.

Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.

*Except Fisheye and Crucible

Overview

The JIRA applications index controls searching and the activity stream, however, it will also query the application's 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 application index files.

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

Changing the indexing language, however, plays a significant part in 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 application 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
com.atlassian.jira.issue.index.IndexException
...

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

Finding out the heaviest custom fields

In Jira Data Center 8.10 onward, go to the Clustering screen, select a node and click Actions > Custom field indexing.

Check Jira Cluster Monitoring for more details.

Debugging indexing

The following classes can be set to DEBUG in order to get more detailed information. Please note this will increase the logs verbosity by a lot, it's recommended to set these back to WARN when done.

com.atlassian.jira.issue.index
com.atlassian.jira.issue.index.DefaultIndexManager
com.atlassian.jira.index.AccumulatingResultBuilder


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 application instance still has threads running; possibly from an earlier JIRA application 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 to:

  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 jira-application.properties file, specifically the value:

Take a thread dump

JIRA will automatically perform 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 on that page.

Knowledge Base Articles

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

Last modified on Feb 16, 2023

Was this helpful?

Yes
No
Provide feedback about this article

In this section

Related content

  • No related content found
Powered by Confluence and Scroll Viewport.