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.

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.

If you specify more than one advanced subquery, all of them are evaluated and replaced in the final search.

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.

  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.

On this page