[Question] [Java] When the registration IDs are inconsistent, deserialization errors are difficult to debug

[moooonk]

Question

I have a system that needs to persist many types of caches to Redis. fory.registeris automatically called during Spring container initialization to register various data classes. Yesterday, I discovered that during system iteration, previously persisted data started causing runtime dynamic type conversion errors. After investigation, I found that data marked as Class A in Redis was being deserialized into Class B objects. The deserialization process didn’t throw any errors—it only failed later during runtime when a generic type cast was enforced.
While I understand that this is due to setting CompatibleMode.COMPATIBLE, which allows field inconsistencies during deserialization, in this case the entire class is inconsistent. After a day of step-by-step debugging, I identified the root cause: the order of automatic registration by the container changed, causing a shift in the class information index and leading to incorrect deserialization results.
Currently, if Fory registration is disabled, a log suggests enabling it. However, the requirement that registration order must remain consistent to avoid serious errors is only mentioned in the API comments of the fory.registerfunction. Could this order-sensitive behavior be highlighted more prominently? Alternatively, is there a solution to make the system compatible with out-of-order registration? In a rapidly iterating large-scale system, maintaining the order of serialized classes or planning IDs for serializable classes is quite cumbersome.
Hi @chaokunyang, hope you can give some advice

[kitalkuyo-gita]

Hi. I'm glad you asked this question. It appears that the automatically assigned ID is serialized into Redis to identify the class type. If the Spring container initialization order changes, the same class might be assigned a different ID, causing the class corresponding to ID 5 to change from Class A to Class B during deserialization.

can see: #2799

it;s mentions enabling Meta Share mode:

Fory fory = Fory.builder()

.withCompatibleMode(CompatibleMode.COMPATIBLE)

.withMetaShare(true)

.build();

When CompatibleMode.COMPATIBLE is enabled, Meta Share is automatically enabled (ForyBuilder.java:402-418). The key benefit of Meta Share is that it includes the full class definition (ClassDef) in the serialized data, not just the class ID (java_serialization_spec.md:115-131).
Including field metadata: Complete field information (field names, types, etc.) of the class is written during serialization. MetaSharedSerializer.java:47-92

Field-level matching: During deserialization, Fory compares the fields in the ClassDef with the fields of the target class for field-level matching and mapping.

Fault-tolerance mechanism: Even if the class ID mismatch occurs, due to the complete field information, Fory can:

• Skip fields that do not exist in the target class
• Use default values ​​for fields missing in the source data
• Intelligent matching based on field names and types
• DifferentPOJOCompatibleSerializerTest.java:58-82

[chaokunyang]

@moooonk For Could this order-sensitive behavior be highlighted more prominently, would you liek to submit a pr to update the document? And for order-insensitive behavior, you can register class by name, which is more flexible, but incur bigger space cost for name serialization

[moooonk]

@chaokunyang Thank you for your reply. Regarding the documentation, I will provide some update later. As for name registration, I fully understand that the design of the registration ID is for the purpose of data header compression. I have reviewed the source code, and it is feasible to modify the registration to use name-based registration. In general, using shorter names for registration may yield slightly worse performance compared to using registration IDs, but it performs better than decoding with full class names in non-registration mode. I believe this is a completely viable solution, and I appreciate your suggestion.
An additional point I’d like to add: Using registration IDs is the default recommendation in most documentation. However, based on the current situation, if improper registration leads to deserialization errors, it may cause silent failures rather than throwing an exception to alert the user early in the deserialization process. If such a situation occurs, it would be very difficult for users to realize that runtime type errors are caused by improper registration. That said, I’m not sure whether the current serialized data includes any mechanism to support early validation of registration ID errors during serialization—it seems there isn’t. Do you have any advice on this?