[Bug][Jira] Unmarshal error for epic description with rich text

[davinogueiradev]

Bug Description

The Jira plugin fails to collect epics when the description field contains rich text (Atlassian Document Format) instead of a plain string. This leads to a JSON unmarshaling error during data collection, causing the pipeline to fail.

Root Cause

The Go struct apiv2models.Issue in backend/plugins/jira/tasks/apiv2models/issue.go defines the Description field as a string. However, the Jira API returns a complex JSON object for rich text fields, causing a type mismatch during JSON unmarshaling.

Stack Trace

attached stack trace -- stack trace: | github.com/apache/incubator-devlake/server/services.runPipeline | /app/server/services/pipeline_runner.go:79 | [...repeated from below...] Wraps: (2) Error running pipeline 3. Wraps: (3) attached stack trace -- stack trace: | github.com/apache/incubator-devlake/server/services.RunTasksStandalone | /app/server/services/task.go:217 | github.com/apache/incubator-devlake/server/services.(*pipelineRunner).runPipelineStandalone.func1 | /app/server/services/pipeline_runner.go:42 | github.com/apache/incubator-devlake/core/runner.runPipelineTasks | /app/core/runner/run_pipeline.go:90 | github.com/apache/incubator-devlake/core/runner.RunPipeline | /app/core/runner/run_pipeline.go:54 | github.com/apache/incubator-devlake/server/services.(*pipelineRunner).runPipelineStandalone | /app/server/services/pipeline_runner.go:38 | github.com/apache/incubator-devlake/server/services.runPipeline | /app/server/services/pipeline_runner.go:76 | github.com/apache/incubator-devlake/server/services.RunPipelineInQueue.func1 | /app/server/services/pipeline.go:358 | runtime.goexit | /usr/local/go/src/runtime/asm_arm64.s:1172 Wraps: (4) attached stack trace | -- stack trace: | | github.com/apache/incubator-devlake/server/services.RunTasksStandalone.func1 | | /app/server/services/task.go:189 | Wraps: (2) Error running task 15. | Wraps: (3) attached stack trace | -- stack trace: | | github.com/apache/incubator-devlake/core/runner.RunPluginSubTasks | | /app/core/runner/run_task.go:333 | | [...repeated from below...] | Wraps: (4) subtask extractEpics ended unexpectedly | Wraps: (5) attached stack trace | -- stack trace: | | github.com/apache/incubator-devlake/helpers/pluginhelper/api.(*StatefulApiExtractor[...]).Execute | | /app/helpers/pluginhelper/api/api_extractor_stateful.go:159 | | github.com/apache/incubator-devlake/plugins/jira/tasks.ExtractEpics | | /app/plugins/jira/tasks/epic_extractor.go:96 | | github.com/apache/incubator-devlake/core/runner.runSubtask | | /app/core/runner/run_task.go:425 | | github.com/apache/incubator-devlake/core/runner.RunPluginSubTasks | | /app/core/runner/run_task.go:330 | | github.com/apache/incubator-devlake/core/runner.RunPluginTask | | /app/core/runner/run_task.go:165 | | github.com/apache/incubator-devlake/core/runner.RunTask | | /app/core/runner/run_task.go:139 | | github.com/apache/incubator-devlake/server/services.runTaskStandalone | | /app/server/services/task_runner.go:114 | | github.com/apache/incubator-devlake/server/services.RunTasksStandalone.func1 | | /app/server/services/task.go:187 | | runtime.goexit | | /usr/local/go/src/runtime/asm_arm64.s:1172 | Wraps: (6) json: cannot unmarshal object into Go struct field .fields.description of type string | Wraps: (7) json: cannot unmarshal object into Go struct field .fields.description of type string | Error types: (1) *withstack.withStack (2) *errutil.withPrefix (3) *withstack.withStack (4) *errutil.withPrefix (5) *withstack.withStack (6) *errutil.withPrefix (7) *json.UnmarshalTypeError Error types: (1) *withstack.withStack (2) *errutil.withPrefix (3) *withstack.withStack (4) *errutil.leafError

Version
v1.0.3-beta4

Are you willing to submit PR?

• Yes I am willing to submit a PR!

Code of Conduct:

• I agree to follow this project's Code of Conduct

[dosubot]

Hi @davinogueiradev! I'm Dosu and I’m helping the incubator-devlake team.

The root cause is confirmed: the Go struct for Jira issues defines the Description field as a string, but Jira sometimes returns this field as a complex object (Atlassian Document Format), which causes a JSON unmarshaling error in the pipeline when rich text is present code reference.

There are no existing tickets or documentation addressing this specific unmarshaling error. The recent update to the Jira epic collector PR #8547 did not resolve this issue.

To handle both plain strings and rich text objects, you’ll need to update the struct to use a custom type for Description and implement custom unmarshaling logic that can process both formats. This approach is common in Go when dealing with fields that may be either a string or an object, especially with APIs like Jira that use ADF for rich text.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[klesh]

Try the "Full Sync" which would delete the existing collected data.

[davinogueiradev]

Try the "Full Sync" which would delete the existing collected data.

yes, I tried, with the new version of Jira API, the response payload has changed too

[klesh]

@d4x1 will release a new beta ASAP to include the fix.

[d4x1]

v1.0.3-beta5