Skip to main content
Version: 1.2.0

Troubleshooting

This page covers common problems when using Fory JavaScript.

Cannot deserialize a non-cross-language payload​

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

Fix: switch the producer to xlang payloads. Java and Go use xlang by default; use compatible mode unless every peer uses the same schema.

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.

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.