From 25fb437b1e6905f38a7ab5578c6e6849339359ee Mon Sep 17 00:00:00 2001
From: Andrzej Ludwikowski <andrzej.ludwikowski@lightbend.com>
Date: Wed, 13 Dec 2023 08:47:11 +0100
Subject: [PATCH] chore: improve error message for JSON deserialization

---
 .../main/java/kalix/javasdk/JsonSupport.java  | 40 ++++++++++++-------
 1 file changed, 26 insertions(+), 14 deletions(-)

diff --git a/sdk/java-sdk-protobuf/src/main/java/kalix/javasdk/JsonSupport.java b/sdk/java-sdk-protobuf/src/main/java/kalix/javasdk/JsonSupport.java
index eb0546a5d1..94853d66eb 100644
--- a/sdk/java-sdk-protobuf/src/main/java/kalix/javasdk/JsonSupport.java
+++ b/sdk/java-sdk-protobuf/src/main/java/kalix/javasdk/JsonSupport.java
@@ -172,19 +172,35 @@ public static <T> T decodeJson(Class<T> valueClass, Any any) {
         } else {
           return objectMapper.readValue(decodedBytes.toByteArray(), valueClass);
         }
+      } catch (JsonProcessingException e) {
+        throw jsonProcessingException(valueClass, any, e);
       } catch (IOException | NoSuchMethodException | InstantiationException | IllegalAccessException |
                InvocationTargetException e) {
-        throw new IllegalArgumentException(
-            "JSON with type url ["
-                + any.getTypeUrl()
-                + "] could not be decoded into a ["
-                + valueClass.getName()
-                + "]",
-            e);
+        throw genericDecodeException(valueClass, any, e);
       }
     }
   }
 
+  private static <T> IllegalArgumentException jsonProcessingException(Class<T> valueClass, Any any, JsonProcessingException e) {
+    return new IllegalArgumentException(
+        "JSON with type url ["
+            + any.getTypeUrl()
+            + "] could not be decoded into a ["
+            + valueClass.getName()
+            + "]. Make sure that changes are backwards compatible or apply a @Migration mechanism (https://docs.kalix.io/java/serialization.html#_schema_evolution).",
+        e);
+  }
+
+  private static <T> IllegalArgumentException genericDecodeException(Class<T> valueClass, Any any, Exception e) {
+    return new IllegalArgumentException(
+        "JSON with type url ["
+            + any.getTypeUrl()
+            + "] could not be decoded into a ["
+            + valueClass.getName()
+            + "]",
+        e);
+  }
+
   private static <T> T migrate(Class<T> valueClass, ByteString decodedBytes, int fromVersion, JsonMigration jsonMigration) throws IOException {
     JsonNode jsonNode = objectMapper.readTree(decodedBytes.toByteArray());
     JsonNode newJsonNode = jsonMigration.transform(fromVersion, jsonNode);
@@ -214,14 +230,10 @@ public static <T, C extends Collection<T>> C decodeJsonCollection(Class<T> value
         ByteString decodedBytes = ByteStringEncoding.decodePrimitiveBytes(any.getValue());
         var typeRef = objectMapper.getTypeFactory().constructCollectionType(collectionType, valueClass);
         return objectMapper.readValue(decodedBytes.toByteArray(), typeRef);
+      } catch (JsonProcessingException e) {
+        throw jsonProcessingException(valueClass, any, e);
       } catch (IOException e) {
-        throw new IllegalArgumentException(
-          "JSON with type url ["
-            + any.getTypeUrl()
-            + "] could not be decoded into a ["
-            + valueClass.getName()
-            + "]",
-          e);
+        throw genericDecodeException(valueClass, any, e);
       }
     }
   }