Summary

Some Jira custom fields and/or custom issues cannot sync with Jira Align. Analyzing the Jira Align logs it is possible to find the following message: “gh.epic.error.not.found”

In the Jira Connector logs, Jira Board in the Jira Align UI does report the following error message:

PUT /rest/luizproject/1.0/epics/XYZWQ-2/add
{"errorMessages":["gh.epic.error.not.found"],"errors":{}}

Environment

Jira Align

Diagnosis

This error was triggered because the Jira is operating with a custom issue type (let’s call it "X”) where, X is a new layer in the Jira Hierarchy, working like Epic → X → Story.

And using the Jira Align settings to manage it, the user set the parameter Jira Align Adminsitration → Jira Setup →  Feature custom field on stories with the X custom field ID, like in the example below:

The parameter “Feature custom field on stories” is responsible to link the Jira story to Epics (Jira Feature), and it only accepts Jira Epics custom field ID.

Cause

Jira Align, with its unique structure and mapping with Jira, operates in a specific way. A visual representation of this can be seen in the figure provided. One of the aspects of this operation is the parameter "Feature custom field on stories." This particular parameter only works with the default "Epic Link" that is derived from Jira. Essentially, this links Features to Stories in the system.

However, this raises a challenge because Jira needs to adhere to the Jira Align data standard of Epic -> Feature (Jira Epic) -> Story.

This process is not feasible due to the inherent design of Jira Align. So, despite the necessity, the required standard cannot be followed due to the constraints of the system.

So because of that, we see that error in the logs.

For more details, please check this documentation -> Jira data synchronization.

Solution

There is no workaround for this situation, so to avoid this error, the user must obey the Jira Align mapping for Jira and use the standard structure.

The parameter Jira Align Adminsitration → Jira Setup →  Feature custom field on stories is the setting responsible to make this link, so fixing the custom field ID set there, will end the error message and establish a link between Jira Story with Epic.