Skip to main content
Version: 1.0.0

Troubleshooting

This page covers common issues and solutions when using cross-language serialization.

Type Registration Errors​

"Type not registered" Error​

Symptom:

Error: Type 'example.Person' is not registered

Cause: The type was not registered before deserialization, or the type name doesn't match.

Solution:

  1. Ensure the type is registered with the same name on both sides:

    // Java
    fory.register(Person.class, "example.Person");
    # Python
    fory.register_type(Person, typename="example.Person")

  2. Check for typos or case differences in type names

  3. Register types before any serialization/deserialization calls

"Type ID mismatch" Error​

Symptom:

Error: Expected type ID 100, got 101

Cause: Different type IDs used across languages.

Solution: Use consistent type IDs:

// Java
fory.register(Person.class, 100);
fory.register(Address.class, 101);
# Python
fory.register_type(Person, type_id=100)
fory.register_type(Address, type_id=101)

Type Mapping Issues​

Integer Overflow​

Symptom: Values are truncated or wrapped unexpectedly.

Cause: Using different integer sizes across languages.

Solution:

  1. In Python, use explicit type annotations:

    @dataclass
    class Data:
        value: pyfory.Int32  # Not just 'int'

  2. Ensure integer ranges are compatible:

    • int8: -128 to 127
    • int16: -32,768 to 32,767
    • int32: -2,147,483,648 to 2,147,483,647

Float Precision Loss​

Symptom: Float values have unexpected precision.

Cause: Mixing float32 and float64 types.

Solution:

  1. Use consistent float types:

    @dataclass
    class Data:
        value: pyfory.Float32  # Explicit 32-bit float

  2. Be aware that Python's float maps to float64 by default

String Encoding Errors​

Symptom:

Error: Invalid UTF-8 sequence

Cause: Non-UTF-8 encoded strings.

Solution:

  1. Ensure all strings are valid UTF-8

  2. In Python, decode bytes before serialization:

    text = raw_bytes.decode('utf-8')

Field Order Issues​

"Field mismatch" Error​

Symptom: Deserialized objects have wrong field values.

Cause: Field order differs between languages.

Solution: Fory sorts fields by their snake_cased names. Ensure field names are consistent:

// Java - fields will be sorted: age, email, name
public class Person {
    public String name;
    public int age;
    public String email;
}
# Python - same field order
@dataclass
class Person:
    name: str
    age: pyfory.Int32
    email: str

Reference Tracking Issues​

Stack Overflow with Circular References​

Symptom:

StackOverflowError or RecursionError

Cause: Reference tracking is disabled but data has circular references.

Solution: Enable reference tracking:

// Java
Fory fory = Fory.builder()
    .withRefTracking(true)
    .build();
# Python
fory = pyfory.Fory(ref=True)

Duplicate Objects​

Symptom: Shared objects are duplicated after deserialization.

Cause: Reference tracking is disabled.

Solution: Enable reference tracking if objects are shared within the graph.

Xlang Type Issues​

Incompatible Types in Xlang Mode​

Symptom:

Error: Type 'Optional' is not supported in xlang mode

Cause: Using Java-specific types that don't have cross-language equivalents.

Solution: Use compatible types:

// Instead of Optional<String>
public String email;  // nullable

// Instead of BigDecimal
public double amount;

// Instead of EnumSet<Status>
public Set<Status> statuses;

Version Compatibility​

Schema Hash Mismatch​

Symptom: Deserialization fails with an error such as class version hash mismatch, schema version mismatch, struct version mismatch, or hash mismatch.

Cause: The writer and reader are using schema-consistent mode while their struct/class schemas differ. In xlang mode this can happen even when each language made a reasonable local change, because field names, type annotations, field IDs, nullability, and generated schema metadata must still align exactly.

Solution:

  1. Align the schemas carefully on every service and language: field names or field IDs, field order where schema-consistent mode requires it, type annotations, nullability, and type registration IDs/names.
  2. Xlang mode defaults to compatible mode in current runtimes. If a peer has explicitly selected schema-consistent mode, remove that override or enable compatible mode on every peer. Compatible mode writes extra schema metadata, so payloads are larger, but it is recommended for xlang services that may evolve independently.
  3. Use schema-consistent mode only when schemas do not change, or when all services deploy the schema change at the same time.

Serialization Format Changed​

Symptom: Deserialization fails after upgrading Fory.

Cause: Breaking changes in serialization format.

Solution:

  1. Ensure all services use compatible Fory versions
  2. Check release notes for breaking changes
  3. Consider using schema evolution (compatible mode) for gradual upgrades

Debugging Tips​

Enable Debug Logging​

Java:

// Add to JVM options
-Dfory.debug=true

Python:

import logging
logging.getLogger('pyfory').setLevel(logging.DEBUG)

Inspect Serialized Data​

Use hex dump to inspect the binary format:

data = fory.serialize(obj)
print(data.hex())

Test Round-Trip​

Always test round-trip serialization in each language:

byte[] bytes = fory.serialize(obj);
Object result = fory.deserialize(bytes);
assert obj.equals(result);

Cross-Language Testing​

Test serialization across all target languages before deployment:

# Serialize in Java
java -jar serializer.jar > data.bin

# Deserialize in Python
python deserializer.py data.bin

Common Mistakes​

  1. Not registering types: Always register custom types before use
  2. Inconsistent type names/IDs: Use the same names/IDs across all languages
  3. Mixing xlang and native payloads: Keep every peer on the xlang wire format
  4. Wrong type annotations: Use markers such as pyfory.Int32 in Python
  5. Ignoring reference tracking: Enable for circular/shared references

See Also​