Skip to main content
Version: 1.0

Troubleshooting

This page covers common issues and their solutions.

Class Inconsistency and Class Version Check​

If you create Fory without enabling compatible mode and you get a strange serialization error, it may be caused by class inconsistency between the serialization peer and deserialization peer.

In such cases, you can invoke ForyBuilder#withClassVersionCheck to create Fory to validate it. If deserialization throws org.apache.fory.exception.ClassNotCompatibleException, it shows classes are inconsistent, and you should create Fory with ForyBuilder#withCompatible(true).

// Enable class version check to diagnose issues
Fory fory = Fory.builder()
  .withClassVersionCheck(true)
  .build();

// If ClassNotCompatibleException is thrown, add compatible mode to the
// same builder configuration on every peer.
ForyBuilder builder = Fory.builder()
  .withCompatible(true);

Note: compatible mode has more performance and space cost. For xlang mode it is the default and recommended setting. Use schema-consistent mode only if your classes are always consistent between serialization and deserialization, or if all services deploy schema changes at the same time.

Using Wrong API for Deserialization​

Use serialize with one of the deserialize overloads:

Serialization APIDeserialization API
Fory#serializeFory#deserialize

Wrong usage example:

// Wrong: deserialize with an incompatible target class
byte[] bytes = fory.serialize(struct1);
Struct2 result = fory.deserialize(bytes, Struct2.class);  // May throw ClassCastException

Correct usage:

byte[] bytes = fory.serialize(object);
Object result = fory.deserialize(bytes);

byte[] typedBytes = fory.serialize(object);
MyClass typedResult = fory.deserialize(typedBytes, MyClass.class);

Deserialize POJO into Another Type​

If you want to serialize one POJO and deserialize it into a different POJO type, enable compatible mode:

public class DeserializeIntoType {
  static class Struct1 {
    int f1;
    String f2;

    public Struct1(int f1, String f2) {
      this.f1 = f1;
      this.f2 = f2;
    }
  }

  static class Struct2 {
    int f1;
    String f2;
    double f3;
  }

  static ThreadSafeFory fory = Fory.builder()
    .withCompatible(true).buildThreadSafeFory();

  public static void main(String[] args) {
    Struct1 struct1 = new Struct1(10, "abc");
    byte[] data = fory.serialize(struct1);
    Struct2 struct2 = fory.deserialize(data, Struct2.class);
  }
}

Common Error Messages​

"Class not registered"​

Cause: Class registration is required but the class wasn't registered.

Solution: Register the class before serialization:

fory.register(MyClass.class);
// or with explicit ID
fory.register(MyClass.class, 100);

"ClassNotCompatibleException"​

Cause: Class schema differs between serialization and deserialization.

Solution: Use compatible mode:

Fory fory = Fory.builder()
  .withCompatible(true)
  .build();

"Max depth exceeded"​

Cause: Object graph is too deep, possibly indicating a circular reference attack.

Solution: Increase max depth if legitimate, or check for malicious data:

Fory fory = Fory.builder()
  .withMaxDepth(100)  // Increase from default 50
  .build();

"Serializer not found"​

Cause: No serializer registered for the type.

Solution: Register a custom serializer:

fory.registerSerializer(MyClass.class, new MyClassSerializer(fory.getTypeResolver()));

Performance Issues​

Slow Initial Serialization​

Cause: JIT compilation happening on first serialization.

Solution: Enable async compilation:

Fory fory = Fory.builder()
  .withAsyncCompilation(true)
  .build();

High Memory Usage​

Cause: Large object graphs or reference tracking overhead.

Solutions:

  • Disable reference tracking if not needed: .withRefTracking(false)
  • Use custom memory allocator for pooling
  • Consider row format for large datasets

Large Serialized Size​

Cause: Metadata overhead or uncompressed data.

Solutions:

  • Enable compression: .withIntCompressed(true), .withLongCompressed(true)
  • Use compatible mode only when needed
  • Register classes to avoid class name serialization

Debugging Tips​

  1. Enable class version check to diagnose schema issues
  2. Check API pairing - ensure serialize/deserialize APIs match
  3. Verify registration order - must be consistent across peers
  4. Enable logging to see internal operations:
FORY_LOG_LEVEL=INFO mvn test -Dtest=org.apache.fory.TestClass#testMethod