Skip to main content
Version: 0.17

Troubleshooting

This page covers common Dart runtime issues and fixes.

Only xlang payloads are supported by the Dart runtime.​

The writer is sending a native-mode (non-xlang) payload. Make sure every service uses the xlang-compatible path:

  • Java: add .withLanguage(Language.XLANG) to the Fory builder.
  • Go: use WithXlang(true) in the Fory options.
  • Other runtimes: check their respective guides for enabling cross-language 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 namespace + typeName).
  2. Stable @ForyField(id: ...) assigned before the first payload was produced.
  3. Compatible numeric widths — use Int32 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: true on both sides if using schema evolution.

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