---
title: Troubleshooting
sidebar_position: 90
id: troubleshooting
license: |
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
---

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.

```ts
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:

```ts
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](references.md).

## 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:

```ts
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.

## Related Topics

- [Basic Serialization](basic-serialization.md)
- [References](references.md)
- [Cross-Language Interoperability](basic-serialization.md#cross-language-interoperability)