Why JQL replaces the custom field name with cf[xxxxx] in Jira Service Management Cloud

Summary

Sometimes, Jira Query Language (JQL) replaces the custom field with its technical ID (cf[xxxxx]) in Jira Service Management Cloud. This makes the JQL hard to read and is not user-friendly.

This article explains why this happens and how to resolve it.

Diagnosis

When performing a JQL search such as project = ITSM and "Request Type" = "Chat", we see that "Request Type" is replaced with cf[10010] in the JQL.

Cause

This behavior typically occurs in Jira Cloud when there is ambiguity with the field name. This is especially seen when multiple fields share the same name, across system fields, global custom fields and fields in team-managed projects.

Example - When there is a field named "Request Type" defined within a team-managed project on the site in addition to the system field with the same name, Jira's JQL engine sees both the system "Request Type" field and the one in the team-managed project, causing it to use the unique ID (cf[10010]) to ensure the query is precise.

Solution

It is clear that Jira uses the unique custom field ID (cf[xxxxx]) in JQL to ensure query precision and avoid ambiguity, even if only one field appears active. Hidden, archived, or project-specific fields with the same name can also trigger this replacement.

This ensures the JQL query targets the correct field, especially when similar field names exist in the environment.

To address this and restore the use of the readable field name, the steps below can be followed:

Identify duplicate or conflicting fields

1. Go to Settings > Work Items > Fields.

2. Search for the field name - example "Request Type".

3. Check if there are multiple entries with this name. Note which is the system field and which is a project-specific field, especially associated with team-managed projects.

4. If found, consider renaming the field in the team-managed project to something more specific (Example - "Local Request Type" or "Project Category").

Optional workaround

1. If renaming the conflicting field is not possible, another solution would be to specify the field type in brackets in the JQL, such as "Request Type[Dropdown]" or "Request Type[Customer Request Type]".

2. Note - This may help Jira distinguish between fields, but renaming is the most reliable solution.

By resolving field name conflicts, Admins can ensure that JQL Queries are readable and user-friendly. If the technical ID still appears, it is recommended to double-check for hidden or archived fields with the same name.