Skip to main content
Version: 1.3

Troubleshooting

This page covers common Dart issues and fixes.

Only xlang payloads are supported by the Dart implementation.​

The writer is sending a native-mode payload. Make sure every peer writes the xlang wire format:

  • Java: configure the peer for xlang mode instead of native mode.
  • Go: configure the peer for xlang mode.
  • Other languages: check their respective guides for xlang mode.

Type ... is not registered.​

Fory does not know how to serialize or deserialize this type. Fix it by:

  1. Running code generation if you haven't: dart run build_runner build --delete-conflicting-outputs
  2. Calling the generated register function (or registerSerializer) for the type before calling serialize or deserialize.
  3. Registering all types that appear in a message, not just the root type. For example, if Order contains an Address, register both.

Generated part file is missing or stale​

Regenerate code:

cd dart/packages/fory
dart run build_runner build --delete-conflicting-outputs

If you moved files or renamed types, rebuild before re-running analysis or tests.

Deserialized value has type ..., expected ...​

The payload describes a different type than T in deserialize<T>. Common causes:

  • You registered the type on the writing side with a different ID or name than on the reading side.
  • The payload was produced by a different code path that serializes a different root object.
  • You are trying to deserialize a heterogeneous container — decode it as Object? or List<Object?> first, then cast.

Objects aren't the same instance after deserialization​

Fory does not track object identity by default, so two fields pointing to the same object will produce two independent copies after a round trip.

To preserve identity:

  • For fields inside a @ForyStruct, add @ForyField(ref: true) to those fields.
  • For a top-level collection, pass trackRef: true to fory.serialize(...).
  • In a custom serializer, use context.writeRef / context.readRef and call context.reference(obj) before reading nested fields.

Cross-language field mismatch (missing data or wrong values)​

Symptoms: fields come back as default values or wrong types after a round trip to another language.

Checklist:

  1. Same registration identity on both sides (same numeric ID or same name).
  2. Stable @ForyField(id: ...) assigned before the first payload was produced.
  3. Compatible numeric widths — use @ForyField(type: Int32Type()) in Dart when the peer field is int (Java), int32 (Go), or int (C#).
  4. Timestamp / LocalDate instead of raw DateTime for date/time fields.
  5. Compatible schema evolution on both sides. Dart enables it by default; make sure peers have not explicitly selected compatible: false.

Int64 or Uint64 values fail on web​

On Dart VM builds, Dart int can represent signed 64-bit values. On Dart web builds, Dart int values are backed by JavaScript numbers and are only precise inside the JS-safe integer range:

-9007199254740991 <= value <= 9007199254740991

If a generated serializer writes an int64 field declared as Dart int, web builds reject values outside that range instead of silently writing corrupted bytes. To exchange full signed 64-bit values on web, declare the field as Fory's Int64 wrapper:

@ForyStruct()
class LedgerEntry {
  LedgerEntry();

  Int64 sequence = Int64(0); // full signed 64-bit range on VM and web
}

For unsigned 64-bit values, prefer Uint64 rather than Dart int. Dart int cannot represent the full uint64 range on either VM or web:

@ForyStruct()
class FileBlock {
  FileBlock();

  Uint64 offset = Uint64(0); // full unsigned 64-bit range
}

@ForyField(type: Int64Type(...)) changes the wire encoding for a Dart int field, but it does not remove the web integer precision limit. Use Int64 for full-range signed values and Uint64 for full-range unsigned values. See Web Platform Support for the full browser support matrix and platform guidance.

Running Tests Locally​

Main Dart package:

dart run build_runner build --delete-conflicting-outputs
dart analyze
dart test

Integration test package:

cd dart/packages/fory-test
dart run build_runner build --delete-conflicting-outputs
dart test

Generated gRPC files cannot find package:grpc types​

Cause: gRPC packages are application dependencies. The fory package does not add gRPC as a hard dependency.

Fix: Add grpc to your pubspec.yaml (and the build_runner dev dependency), then run dart pub get. See gRPC Support.

A protobuf client cannot decode a Fory gRPC service​

Cause: Fory gRPC companions use gRPC transports with Fory-encoded message bodies, not protobuf wire encoding.

Fix: Use a Fory-generated client for Fory-generated services, or expose a separate protobuf service endpoint for generic protobuf clients.