Configuration

This page explains the Fory constructor options.

Creating a Fory Instance

Pass options directly to the constructor:

import 'package:fory/fory.dart';

// defaults: xlang wire format with compatible schema evolution
final fory = Fory();

// customize limits while keeping default compatible mode
final fory = Fory(
  maxDepth: 512,
  maxTypeFields: 512,
  maxTypeMetaBytes: 4096,
  maxSchemaVersionsPerType: 10,
  maxAverageSchemaVersionsPerType: 3,
  maxGraphMemoryBytes: 64 * 1024 * 1024,
  maxUnbackedContainerItems: 8192,
);

Create one instance per application and reuse it; there is no benefit to creating a new Fory per request.

Options

compatible

Compatible mode is enabled by default. Keep it enabled when your service needs to handle payloads from different versions of the same model, for example during rolling deployments or client/server version skew.

When compatible: true:

• Adding or removing fields on one side does not break the other.
• Peers must still use the same name (or numeric id) to identify types.

When compatible: false:

• Both sides must have exactly the same schema. Use this only when every reader and writer always uses that schema and you want faster serialization and smaller size. For cross-language payloads, set compatible: false only after verifying that every language uses the same schema, or when native types are generated from Fory schema IDL.

final fory = Fory(compatible: false);

checkStructVersion

Relevant only when compatible: false. When true, Fory validates that the schema version in the payload matches the one the receiver knows about, catching accidental mismatches for intentional same-schema payloads.

final fory = Fory(
  compatible: false,
  checkStructVersion: true, // default
);

This option has no effect when compatible: true.

maxDepth

Limits how deeply nested an object graph can be. Increase this if you have legitimately deep trees; lower it to reject unexpectedly deep payloads fast.

final fory = Fory(maxDepth: 128);

Remote schema metadata limits

Compatible mode can receive remote metadata for schema evolution. These limits bound metadata size and accepted schema versions:

final fory = Fory(
  maxTypeFields: 512,
  maxTypeMetaBytes: 4096,
  maxSchemaVersionsPerType: 10,
  maxAverageSchemaVersionsPerType: 3,
);

• maxTypeFields limits fields in one received struct metadata body.
• maxTypeMetaBytes limits encoded body bytes in one received TypeMeta body, excluding the 8-byte header and any extended-size varint.
• maxSchemaVersionsPerType limits accepted remote metadata versions for one logical type.
• maxAverageSchemaVersionsPerType limits the average across accepted remote types. The effective global floor is 8192 schemas.

maxGraphMemoryBytes

Sets an approximate graph-memory gate for one root deserialization. The estimate mainly covers materialized lists, sets, maps, arrays, structs, and objects. It skips leaf values such as strings, binary data, primitive scalars, and dense typed-array payloads, so actual process memory can be higher than this value. Leaf values remain protected by byte-availability checks: if the unread input does not contain enough bytes, Fory will not read or create that leaf value.

The default is a fixed 128 MiB and is not derived from input size.

Set a positive value when a trusted workload legitimately needs a larger or smaller collection/map/struct gate:

final fory = Fory(maxGraphMemoryBytes: 256 * 1024 * 1024);

Explicit non-positive values are rejected when the Fory instance is created.

maxUnbackedContainerItems

Limits collection elements and map entries whose repeated read bodies do not consume proportional input during one root deserialization. The default is 8192; zero is a strict limit.

final fory = Fory(maxUnbackedContainerItems: 8192);

Defaults

Option	Default
compatible	true
checkStructVersion	false
maxDepth	256
maxTypeFields	512
maxTypeMetaBytes	4096
maxSchemaVersionsPerType	10
maxAverageSchemaVersionsPerType	3
maxGraphMemoryBytes	134217728
maxUnbackedContainerItems	8192

Xlang Notes

When Fory is used to communicate between services written in different languages:

• Keep compatible mode enabled on all sides if any side needs schema evolution.
• Use the same numeric IDs or name values on every side.
• Match the compatible setting on both the writing and reading side — mismatching modes will fail.

Security

See Dart Security for trust boundaries, safe reader configuration, and verification.

Related Topics

• Basic Serialization
• Schema Evolution
• Cross-Language Interoperability