Troubleshooting

This page covers common issues and debugging techniques for Apache Fory™ Rust.

Common Issues

Type Registry Errors

Error: TypeId ... not found in type_info registry

Cause: The type was never registered with the current Fory instance.

Solution: Register the type before serialization:

let mut fory = Fory::default();
fory.register::<MyStruct>(100)?;  // Register before use

Confirm that:

• Every serializable struct or trait implementation calls fory.register::<T>(type_id)
• The same IDs are reused on the deserialize side

Type Mismatch Errors

Cause: Field types are incompatible or schema has changed.

Solution:

• Enable compatible mode for schema evolution
• Ensure field types match across versions

let fory = Fory::default().compatible(true);

Debugging Techniques

Enable Panic on Error for Backtraces

Toggle FORY_PANIC_ON_ERROR=1 alongside RUST_BACKTRACE=1 to panic at the exact site an error is constructed:

RUST_BACKTRACE=1 FORY_PANIC_ON_ERROR=1 cargo test --features tests

Reset the variable afterwards to avoid aborting user-facing code paths.

Struct Field Tracing

Add the #[fory(debug)] attribute alongside #[derive(ForyObject)] to emit hook invocations:

#[derive(ForyObject)]
#[fory(debug)]
struct MyStruct {
    field1: i32,
    field2: String,
}

Once compiled with debug hooks, call these functions to plug in custom callbacks:

• set_before_write_field_func
• set_after_write_field_func
• set_before_read_field_func
• set_after_read_field_func

Use reset_struct_debug_hooks() when you want the defaults back.

Lightweight Logging

Without custom hooks, enable ENABLE_FORY_DEBUG_OUTPUT=1 to print field-level read/write events:

ENABLE_FORY_DEBUG_OUTPUT=1 cargo test --features tests

This is especially useful when investigating alignment or cursor mismatches.

Inspect Generated Code

Use cargo expand to inspect code generated by Fory derive macros:

cargo expand --test mod $mod$::$file$ > expanded.rs

Running Tests

Run All Tests

cargo test --features tests

Run Specific Test

cargo test -p tests --test $test_file $test_method

Run Test with Debugging

RUST_BACKTRACE=1 FORY_PANIC_ON_ERROR=1 ENABLE_FORY_DEBUG_OUTPUT=1 \
  cargo test --test mod $dir$::$test_file::$test_method -- --nocapture

Test-Time Hygiene

Some integration tests expect FORY_PANIC_ON_ERROR to remain unset. Export it only for focused debugging sessions:

# For specific debugging only
FORY_PANIC_ON_ERROR=1 cargo test -p tests --test specific_test -- --nocapture

# Normal test run (without panic on error)
cargo test --features tests

Error Handling Best Practices

Prefer the static constructors on fory_core::error::Error:

• Error::type_mismatch
• Error::invalid_data
• Error::unknown

This keeps diagnostics consistent and makes opt-in panics work correctly.

Quick Reference

Environment Variable	Purpose
RUST_BACKTRACE=1	Enable stack traces
FORY_PANIC_ON_ERROR=1	Panic at error site for debugging
ENABLE_FORY_DEBUG_OUTPUT=1	Print field-level read/write events

Related Topics

• Configuration - Fory options
• Type Registration - Registration best practices
• Schema Evolution - Compatible mode