Troubleshoot Enhanced Search for Jira Cloud

Overview

From the outset, you should adhere to the following guidance:

• Ensure JQL keywords are synced. It can appear that JQL queries don't work when, in fact, they just haven't been synced.
• As there are timeout limitations in the Cloud (two minutes maximum), you should endeavour to reduce the complexity of queries and make them as small as possible to avoid these. The two minute timeout currently applies to searches made in the Enhanced Search app only, whereas any saved filters are subject to the 30 second search timeout limit when syncing.
• Build queries using the Insert Function option where possible, as this helps ensure the correct syntax.
• Ensure filters are synced automatically when powering dashboards or Agile boards so that issues returned by a JQL query are up to date. You can toggle the filter sync filter by editing a filter.
• Avoid tweaking permissions for the Add-On User, as this can cause many functions to not work as expected. This is particularly the case when restricting permissions.
• Use IDs rather than names in ES functions, where possible.

(<number of issues in instance> * 0.00029) / 50

Filter Syncing Delays

When you save a JQL filter, our system syncs it in the background at regular intervals to give you the latest results. However, some factors can lead to occasional delays or incomplete updates.

What to know about filter syncing

• Sync Interval: The sync interval you set is the minimum time between checks to update your filters, i.e. how often we update your search results. However, actual updates may vary depending on filter complexity and whether filters are still being synced from a previous sync interval.

• A long-running filter is one that processes a large data set.

• Account Syncing Limits: Syncing happens independently for each user account. If a sync is already in progress for your account, new syncs will wait until the current one finishes. This ensures data consistency but can mean your filters may not update at the regularity of your sync interval.

Common reasons for sync delays

• Complex Filters: Filters with lots of data, complex queries, or custom functions (like linkedIssuesOf) take longer to sync. This can delay updates for other filters in the same account.

• Timeouts: Syncing has a 5-minute time limit. Filters that need more time may not fully update in each cycle. If a filter regularly hits this time limit, it will likely time out regularly during syncing.

When sync improvements aren't possible

In certain situations, there may be no effective way to improve sync frequency or reliability. For example:

• Extremely Long-running Filters: If a filter takes longer than 5 minutes to run, it will not complete syncing within the time limit, and there’s no optimisation available that can change this.

• Heavy Data Filters: Filters that rely on extremely large datasets or involve intensive calculations (like multiple nested functions) may also reach technical limits. If the system cannot sync them within the available time, they will not update as frequently, no matter what changes are made.

In these cases, if syncing frequency or reliability is critical, consider simplifying the filter’s logic or using alternative filters with reduced complexity. If that’s not possible, you may need to manually refresh the results or adjust expectations for real-time updates.

Tips for faster filter syncing

• Simplify long-running filters

  • If you have filters with complex queries, custom functions, or large data sets, try to simplify them where possible. Long-running filters can delay syncing for other filters within the same account. See our Tips for Writing Queries.

• Delete unused filters:

  • If you have filters that aren’t being used, consider deleting them. This frees up syncing resources, allowing active filters to sync more efficiently.

• Limit use of functions like linkedIssuesOf and parentsOf which add processing time. Use these sparingly for filters that need to sync frequently.

FAQs

Why isn’t my filter updating as frequently as I expected?

• The sync interval you set is how often we update your search results, but actual syncing frequency can vary. This can happen if:

  • You have long-running filters (complex queries, large data volumes, or using functions like linkedIssuesOf or parentsOf) that take time to sync.

  • Another sync is already in progress for your account, causing new syncs to wait until the current one completes.

• To improve syncing, try simplifying any complex filters, removing unused filters, and setting realistic expectations for highly complex filters.

What can I do if my filters aren’t syncing reliably?

• Here are a few things you can try:

  • Simplify complex filters to reduce sync time.

  • Delete any unused filters that may be taking up sync resources.

  • Adjust sync intervals for complex or long-running filters to allow more time for each sync to complete.

• If you’ve tried these steps and still see issues, please reach out to support for further assistance.

Do unused filters affect syncing?

• Yes, unused filters can impact syncing. Even if a filter is short-running, it still takes up resources during each sync cycle. Deleting or archiving filters you don’t actively use can help free up resources and improve sync performance for the filters you rely on.

Can all filters be synced reliably, no matter how complex they are?

• Not always. Filters that take longer than 5 minutes to process may not sync, which can lead to incomplete updates or delays. If a filter is highly complex or processes a large amount of data, there may be no way to improve its sync reliability. For such filters, consider simplifying them or adjusting your expectations for real-time updates.

Common Errors

Issues with Renamed or Customized Epic Fields

If you've renamed or customized the Epic Link default field in your Jira instance, you may notice issues with epic-related queries in Enhanced Search, such as:

• Failures with getting automatic syncing and the most up-to-date results.

• Epic-related JQL functions (e.g., epicsOf, linkedIssuesOf) not returning expected results.

Cause:

Atlassian has deprecated the Epic Link field and now recommends using the Parent property to link to epics. Since the Epic Link field was customizable, any epic fields that you have renamed or customized are no longer supported in JQL queries.

Resolution:

To ensure your queries work smoothly, we recommend updating to Jira’s Parent field configuration to ensure compatibility.

Filter Search Results Not Automatically Updated 

This happens when the time it takes for your query to complete exceeds the sync interval (i.e., how often we update your search results) limit of five minutes. This may also happen if a filter is unused for 2+ months.

Resolution options:

• Manually refresh the filter: 
  Locate the saved filter and click refresh to get the most up-to-date results, as highlighted below.
  

• Simplify your query:
  Reduce the complexity or narrow down your search criteria. This helps the query to complete faster and fall within the sync interval rate. See our Tips for Writing Queries for more details.

Incorrect Board ID in Sprint Functions

• Sprint functions such as previousSprint() do not return expected results.

• The board ID believed to be correct does not align with current sprint data.

Cause:

This issue typically arises when teams switch to using a shared central board for sprint management but continue using an old board ID in their queries.

Resolution steps:

1. Verify the current board configuration:

   • Navigate to your Jira scrum board settings to confirm the board ID currently managing sprints. You must use the board ID of the board that the sprint was created from.

2. Update JQL functions:

   • Replace the board ID in your JQL functions with the ID of the centralized sprint board.

   • Example: Change all instances of previousSprint(boardId=234) to previousSprint(boardId=205).

3. Test the changes:

   • Run your queries to ensure they are now returning the correct issues.

Slow Performance with Negative Operators

• Queries using negative operators (e.g., not in, !=) take longer than expected to execute.

• Performance issues are more pronounced in larger Jira instances.

Cause:

Negative operators expand the search scope, requiring the system to process a larger dataset to exclude specified values.

Resolution steps:

1. Optimize JQL queries:

   • Combine negative operators with positive conditions to reduce the dataset being queried.

   • Example: Instead of status != "Closed", use status != "Closed" AND createdDate >= -30d.

2. Narrow the query scope:

   • Include additional limiting JQL clauses like project keys or specific fields.

   • Example: assignee in (currentUser()) AND status not in (Closed, Resolved).

3. Refine your approach:

   • Evaluate if a more straightforward query could achieve the desired results without using negative operators.

Search API

In addition to the main features of Enhanced Search for Jira Cloud, some features also run in the background. The only way to search and retrieve data without access to underlying databases is by using the Search API. Enhanced Search works by making simple queries to available APIs, and processing the results in various ways (using pattern matching, comparing, aggregation, etc).

For example:

assignee = currentUser() AND issueFunction in dateCompare("project = DEMO", "created +1w < firstCommented") AND status = "In progress"

This contains a nested query. As you can see, the dateCompare function in the middle of the expression is not natively supported by Jira Cloud. The query is parsed, and the dateCompare subquery is processed first. A standard search is made using the subquery "project = DEMO", then a comparison expression is applied to the results. Finally, a search is made to Jira Cloud with the structure:

assignee = currentUser() AND issue in ("10012", "10013", "10055") AND status = "In progress"

As seen above, the dateCompare query has been replaced by another query:`issue in (..)`. It contains issue ids/keys that were evaluated from the subquery.