fix: handle missing @reference entities gracefully (#607)

- Add null checks in ReferenceDeserializer to prevent NPE when referenced entities are missing
- Add null check in JSONOperationsImpl.get() to handle null results from Redis
- Log warnings when referenced entities cannot be found
- Filter out missing references from collections instead of throwing NPE
- Add tests to verify proper handling of missing single and collection references

Author: bsbodden

redis-om-spring/src/main/java/com/redis/om/spring/ops/json/JSONOperationsImpl.java

@@ -61,7 +61,9 @@ public Long del(K key, Path2 path) {
   @Override
   public String get(K key) {
     var result = client.clientForJSON().jsonGet(key.toString(), Path2.ROOT_PATH);
-    if (result instanceof JSONArray jsonArray) {
+    if (result == null) {
+      return null;
+    } else if (result instanceof JSONArray jsonArray) {
       return !jsonArray.isEmpty() ? jsonArray.get(0).toString() : null;
     } else if (result instanceof LinkedTreeMap<?, ?> linkedTreeMap) {
       return getGson().toJson(linkedTreeMap);

redis-om-spring/src/main/java/com/redis/om/spring/serialization/gson/ReferenceDeserializer.java

@@ -106,10 +106,18 @@ public Object deserialize(JsonElement json, Type typeOfT, JsonDeserializationCon
       }
       if (referenceJSON == null) {
         referenceJSON = ops.get(referenceKey);
-        if (referenceCache != null && shouldCache(type)) {
+        if (referenceJSON != null && referenceCache != null && shouldCache(type)) {
           referenceCache.put(referenceKey, referenceJSON);
         }
       }
+
+      // Handle missing reference gracefully
+      if (referenceJSON == null) {
+        logger.warn(String.format("Referenced entity with key '%s' not found for type %s", referenceKey, type
+            .getName()));
+        return null;
+      }
+
       jsonObject = gson.fromJson(referenceJSON, JsonObject.class);
       reference = deserializeEntity(jsonObject, context);
     } else if (json.isJsonObject()) {
@@ -139,8 +147,19 @@ public Object deserialize(JsonElement json, Type typeOfT, JsonDeserializationCon
         } else {
           values = ops.mget(keys);
         }
-        ((Collection) reference).addAll(values.stream().map(raw -> gson.fromJson(raw, JsonObject.class)).map(
-            jo -> deserializeEntity(jo, context)).toList());
+        // Filter out null values (missing references) and log warnings
+        List<Object> deserializedReferences = new ArrayList<>();
+        for (int i = 0; i < values.size(); i++) {
+          String raw = values.get(i);
+          if (raw != null) {
+            JsonObject jo = gson.fromJson(raw, JsonObject.class);
+            deserializedReferences.add(deserializeEntity(jo, context));
+          } else {
+            logger.warn(String.format("Referenced entity with key '%s' not found for type %s", keys[i], type
+                .getName()));
+          }
+        }
+        ((Collection) reference).addAll(deserializedReferences);
       }
     }
 

tests/src/test/java/com/redis/om/spring/annotations/document/ReferenceTest.java

@@ -1,6 +1,7 @@
 package com.redis.om.spring.annotations.document;
 
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
 
 import java.util.*;
 import java.util.stream.Collectors;
@@ -286,4 +287,57 @@ void testExtremeReferencesWithFindAll() {
       assertThat(tmr.getRef10()).isNotNull();
     }
   }
+
+  @Test
+  void testNPEWithMissingReference() {
+    // First create a city with a valid state reference
+    var usa = countryRepository.save(Country.of("USA"));
+    var fl = stateRepository.save(State.of("FL", "Florida", usa));
+    var miami = cityRepository.save(City.of("Miami", fl));
+
+    // Verify the city was saved correctly
+    var savedCity = cityRepository.findById("Miami");
+    assertThat(savedCity).isPresent();
+    assertThat(savedCity.get().getState().getId()).isEqualTo("FL");
+
+    // Now delete the state that the city references
+    stateRepository.deleteById("FL");
+
+    // Verify the state is gone
+    var deletedState = stateRepository.findById("FL");
+    assertThat(deletedState).isEmpty();
+
+    // After the fix, this should no longer throw NPE
+    // Instead, it should return the city with null state reference
+    var cityWithMissingRef = cityRepository.findById("Miami");
+    assertThat(cityWithMissingRef).isPresent();
+    assertThat(cityWithMissingRef.get().getId()).isEqualTo("Miami");
+    assertThat(cityWithMissingRef.get().getState()).isNull();
+  }
+
+  @Test
+  void testCollectionWithMissingReferences() {
+    // Create states and a collection referencing them
+    var usa = countryRepository.save(Country.of("USA"));
+    var ny = stateRepository.save(State.of("NY", "New York", usa));
+    var nj = stateRepository.save(State.of("NJ", "New Jersey", usa));
+    var ct = stateRepository.save(State.of("CT", "Connecticut", usa));
+
+    var statesCollection = statesRepository.save(States.of("Tri-State Area", Set.of(ny, nj, ct)));
+
+    // Verify the collection was saved correctly
+    var saved = statesRepository.findById("Tri-State Area");
+    assertThat(saved).isPresent();
+    assertThat(saved.get().getStates()).hasSize(3);
+
+    // Delete one of the referenced states
+    stateRepository.deleteById("NJ");
+
+    // Retrieving the collection should not throw NPE
+    // It should only contain the existing states
+    var collectionWithMissingRef = statesRepository.findById("Tri-State Area");
+    assertThat(collectionWithMissingRef).isPresent();
+    assertThat(collectionWithMissingRef.get().getStates()).hasSize(2);
+    assertThat(collectionWithMissingRef.get().getStates()).extracting("id").containsExactlyInAnyOrder("NY", "CT");
+  }
 }