Troubleshoot Enhanced Search for Jira Cloud
Enhanced Search troubleshooting overview
| Symptom / Error | Likely Cause | Error Category | What to Check First | Recommended Fix |
|---|---|---|---|---|
| Search times out or never completes. | Query processes too many issues or is too complex. | Timeouts and Performance | Query size, negative operators. | Narrow scope, split queries, add date or project filters. |
| Search fails intermittently during heavy instance activity. | Too many searches in a short period. | Rate Limits | Frequency of searches, automation, or scripts. | Turn off automatic syncing for filters that don't need it, audit and delete old or unused filters. |
| Search returns no results, but no error. | Filters are too narrow or exclude valid issues. | Empty or Missing Results | AND/OR logic, empty fields, deprecated fields. | Broaden filters, include EMPTY checks, and validate fields. Check custom issue types as some functions work with these, and some don't. For example, |
| Query fails to run or save. | Invalid syntax or unsupported function. | Errors | JQL syntax, function usage. | Fix syntax, use supported fields/functions. |
| Unable to save filter. | Filter name conflict or timeout during save. | Errors | Existing filter names, query complexity. | Rename filter, simplify query. |
Best practice tips
- Ensure JQL keywords are synced: It can appear that JQL queries don't work when, in fact, they just haven't been synced.
- Use the insert function: Build queries using the Insert Function '+' option where possible, as this helps ensure the correct syntax.
- Avoid timeout limits: 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.
- Enable the filter sync: 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.
- Permissions: 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 in ES functions: Use IDs rather than names in ES functions, where possible. For example, filter IDs, Atlassian user account IDs, board IDs, sprint IDs, and so on.
The image below summarises how you can write efficient queries and how you can avoid writing inefficient ones:
