Skip to main content
Version: 0.17

Troubleshooting

This page covers common problems when using Fory JavaScript.

Cannot deserialize a non-cross-language payload​

The Fory JavaScript runtime only reads Fory cross-language payloads. If the producer is a Java or Go service using a language-native format, the JavaScript side cannot decode it.

Fix: switch the producer to the cross-language mode. For Java, use .withLanguage(Language.XLANG); for Go, use WithXlang(true).

maxDepth must be an integer >= 2​

This means you passed an invalid maxDepth value. It must be a positive integer of at least 2.

new Fory({ maxDepth: 100 });

Increase this only if your data is legitimately deeply nested.

Binary size ... exceeds maxBinarySize​

A binary field or the overall message exceeded the safety limit. If the size is expected and the source is trusted, increase the limit:

new Fory({ maxBinarySize: 128 * 1024 * 1024 });

Collection size ... exceeds maxCollectionSize​

A list, set, or map has more elements than the configured limit. This often means the data is unexpectedly large. If it is legitimate, increase the limit:

new Fory({ maxCollectionSize: 2_000_000 });

Field "..." is not nullable​

You are passing null to a field that was not declared nullable. Fix: add .setNullable(true) to the field schema:

const userType = Type.struct("example.user", {
  name: Type.string(),
  email: Type.string().setNullable(true), // ← this field can be null
});

Objects are not the same instance after deserialization​

Fory does not preserve object identity by default. Two fields pointing to the same object will become two independent copies.

Fix: enable both of these:

  1. new Fory({ ref: true }) on the instance
  2. .setTrackingRef(true) on the specific fields

See References.

Large integers come back as bigint​

This is expected. Fory uses bigint for any 64-bit integer field (Type.int64(), Type.uint64()). If you need a number, use a smaller integer type like Type.int32() — but only if the value actually fits in 32 bits.

Inspecting Generated Serializer Code​

If you need to debug what Fory is doing under the hood, inspect the generated serializer code with a hook:

const fory = new Fory({
  hooks: {
    afterCodeGenerated(code) {
      console.log(code);
      return code;
    },
  },
});

@apache-fory/hps Install Fails​

@apache-fory/hps is an optional Node.js accelerator. If it fails to install (e.g. on a platform without native module support), just remove it from your dependencies. Fory still works correctly without it.