Fix EntityReference deserialization error when listing entities with sortBy (#28616)

Listing entities with `sortBy` routes to the search-index path, which rebuilds
each entity from the Elasticsearch `_source`. Search documents store `followers`
as a flat list of UUID strings (keyword field), which cannot be deserialized into
the entity's `List<EntityReference> followers`, producing a 400 on endpoints like
`/contextCenter/pages?sortBy=updatedAt`.

Normalize followers back into user EntityReferences before deserialization in
EntityRepository.listFromSearchWithOffset. The read-side fix preserves the
keyword-ID index format that the follow/unfollow painless scripts depend on, so
no reindex is required. Applies to every entity that uses this search list path.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
(cherry picked from commit cfa9238)

Author: 2 people

openmetadata-service/src/main/java/org/openmetadata/service/jdbi3/EntityRepository.java

@@ -244,6 +244,7 @@
 import org.openmetadata.service.resources.teams.RoleResource;
 import org.openmetadata.service.rules.RuleEngine;
 import org.openmetadata.service.search.PropagationDescriptor;
+import org.openmetadata.service.search.SearchIndexUtils;
 import org.openmetadata.service.search.SearchListFilter;
 import org.openmetadata.service.search.SearchRepository;
 import org.openmetadata.service.search.SearchResultListMapper;
@@ -4053,6 +4054,7 @@ public ResultList<T> listFromSearchWithOffset(
               subjectContext);
       total = results.getTotal();
       for (Map<String, Object> json : results.getResults()) {
+        SearchIndexUtils.normalizeFollowers(json);
         T entity = JsonUtils.readOrConvertValueLenient(json, entityClass);
         entityList.add(withHref(uriInfo, entity));
       }

openmetadata-service/src/main/java/org/openmetadata/service/search/SearchIndexUtils.java

@@ -19,6 +19,7 @@
 import java.util.Map;
 import java.util.Optional;
 import java.util.Set;
+import java.util.UUID;
 import java.util.stream.Collectors;
 import lombok.Getter;
 import lombok.extern.slf4j.Slf4j;
@@ -36,6 +37,7 @@
 import org.openmetadata.schema.type.change.ChangeSource;
 import org.openmetadata.schema.type.change.ChangeSummary;
 import org.openmetadata.schema.utils.JsonUtils;
+import org.openmetadata.service.Entity;
 import org.openmetadata.service.TypeRegistry;
 import org.openmetadata.service.util.Utilities;
 
@@ -166,6 +168,32 @@ public static List<String> parseFollowers(List<EntityReference> followersRef) {
     return followersRef.stream().map(item -> item.getId().toString()).toList();
   }
 
+  /**
+   * Search documents store {@code followers} as a flat list of user-id strings (see {@link
+   * #parseFollowers}). When a search hit is converted back into an entity, that string list cannot
+   * be deserialized into the entity's {@code List<EntityReference> followers} field. This rebuilds
+   * each id into a user {@link EntityReference} so the entity deserializes cleanly.
+   */
+  public static void normalizeFollowers(Map<String, Object> sourceAsMap) {
+    Object followers = sourceAsMap.get(EntityBuilderConstant.FIELD_FOLLOWERS);
+    if (followers instanceof List<?> followerList && !followerList.isEmpty()) {
+      sourceAsMap.put(EntityBuilderConstant.FIELD_FOLLOWERS, expandFollowerIds(followerList));
+    }
+  }
+
+  private static List<Object> expandFollowerIds(List<?> followerList) {
+    List<Object> followers = new ArrayList<>();
+    for (Object follower : followerList) {
+      if (follower instanceof String followerId) {
+        followers.add(
+            new EntityReference().withId(UUID.fromString(followerId)).withType(Entity.USER));
+      } else {
+        followers.add(follower);
+      }
+    }
+    return followers;
+  }
+
   public static List<String> parseOwners(List<EntityReference> ownersRef) {
     if (ownersRef == null) {
       return Collections.emptyList();

openmetadata-service/src/test/java/org/openmetadata/service/search/SearchIndexUtilsTest.java

@@ -13,6 +13,7 @@
 import java.util.UUID;
 import org.junit.jupiter.api.Test;
 import org.mockito.MockedStatic;
+import org.openmetadata.schema.entity.data.Page;
 import org.openmetadata.schema.entity.data.Table;
 import org.openmetadata.schema.entity.data.Topic;
 import org.openmetadata.schema.tests.DataQualityReport;
@@ -25,6 +26,8 @@
 import org.openmetadata.schema.type.TagLabel;
 import org.openmetadata.schema.type.change.ChangeSource;
 import org.openmetadata.schema.type.change.ChangeSummary;
+import org.openmetadata.schema.utils.JsonUtils;
+import org.openmetadata.service.Entity;
 import org.openmetadata.service.TypeRegistry;
 
 class SearchIndexUtilsTest {
@@ -63,6 +66,41 @@ void testParseHelpersAndRemoveFieldByPathSupportsNestedLists() {
     assertFalse(doc.containsKey("simple"));
   }
 
+  @Test
+  void testNormalizeFollowersExpandsIdStringsIntoEntityReferences() {
+    UUID followerId = UUID.randomUUID();
+    Map<String, Object> source = new HashMap<>();
+    source.put("id", UUID.randomUUID().toString());
+    source.put("name", "test-page");
+    source.put("pageType", "Article");
+    source.put("followers", new ArrayList<>(List.of(followerId.toString())));
+
+    assertThrows(
+        IllegalArgumentException.class,
+        () -> JsonUtils.readOrConvertValueLenient(source, Page.class));
+
+    SearchIndexUtils.normalizeFollowers(source);
+    Page page = JsonUtils.readOrConvertValueLenient(source, Page.class);
+
+    assertEquals(1, page.getFollowers().size());
+    EntityReference follower = page.getFollowers().getFirst();
+    assertEquals(followerId, follower.getId());
+    assertEquals(Entity.USER, follower.getType());
+  }
+
+  @Test
+  void testNormalizeFollowersLeavesEmptyOrMissingFollowersUntouched() {
+    Map<String, Object> missing = new HashMap<>();
+    missing.put("name", "no-followers");
+    SearchIndexUtils.normalizeFollowers(missing);
+    assertFalse(missing.containsKey("followers"));
+
+    Map<String, Object> empty = new HashMap<>();
+    empty.put("followers", new ArrayList<>());
+    SearchIndexUtils.normalizeFollowers(empty);
+    assertEquals(List.of(), empty.get("followers"));
+  }
+
   @Test
   void testBuildAggregationTreeAndParseMetricAggregationReport() {
     SearchAggregation aggregation =