Preventing crashes with JQL resilience
You can use JQL resilience features if you're using the Lucene search engine on your Jira.
JQL resilience is a set of features that help prevent node crashes caused by resource-intensive JQL operations. To stop a JQL query from using too much memory or running for too long, you can:
Search results limits: set a maximum search result limit.
JQL query timeout: define a JQL query time limit to interrupt queries that run too long.
Memory circuit breaker: enable a memory usage circuit breaker to reject new JQL queries when memory is low.
Each time a limit is reached, the audit log records the query that triggered the limit and the reason for the failure. This helps you track which queries reach limits most often, identify recurring issues, and ensure smoother automated processes by preventing repeated failures.
If the query is triggered by an automation rule, an exception is thrown during rule processing, and it's the responsibility of the automation feature to log it.
Before you begin
These features are potentially disruptive. While they're preferable to a node crash, they can still impact Jira’s behavior for users and automation, causing actions to fail. For example, some JQL searches might return a SearchException in situations that didn’t cause one before, such as timeouts.
Enabling JQL resilience
Don’t set the JQL resilience limits lightly. Only use them if the alternative is a node crash or if failing such JQL searches is acceptable.
You can control the JQL resilience features in the jira-config.properties file. Enable JQL resilience features for each node separately:
In the
jira-config.propertiesfile, add or update the relevant feature flags and properties. More about advanced Jira configurationSave your changes.
Restart Jira for the changes to take effect.
Search results limits
You can set the maximum number of search results returned by a JQL query.
Feature flag:
com.atlassian.jira.lucene.search.limit. This feature is turned off by default.Related system property:
jira.search.platform.max.result.windowDefault value:
10000
JQL query timeout
You can automatically interrupt JQL queries that exceed a specified execution time.
There’s no feature flag for this feature.
Related system property:
jira.search.lucene.query.timeout.msDefault value:
0
The timeout is disabled if the property is absent, set to 0, or set to a negative value. To enable query interruption, set a positive value in milliseconds.
Memory circuit breaker
You can prevent Jira from accepting new JQL queries when memory consumption exceeds a defined threshold.
Feature flag:
com.atlassian.jira.lucene.search.memory.circuit.breaker. This feature is turned off by default.Related system property:
jira.lucene.search.memory.circuit.breaker.percentageDefault value:
95
Error rendering
By default, when a query fails because of the JQL limits, users receive a notification message about the failure. You can control whether errors are rendered in the UI for users with the following feature flag: com.atlassian.jira.search.error.polling.and.rendering.
Turning error rendering off won’t affect already applied limits.
Identifying slow JQL queries
You might also want to identify and analyze slow JQL queries using Jira’s built-in logging and diagnostic tools. Explore how to identify slow JQL queries