What causes "deserialize_tuple_struct is not implemented" in tracel-ai/burn?

Convert the tuple struct to a named-field struct so it deserializes via deserialize_struct.

deserialize_tuple_struct is not implemented

Error message

deserialize_tuple_struct is not implemented

What it means

The nested-value deserializer panics on `deserialize_tuple_struct` because tuple structs (e.g., `struct Id(u32)`) have no NestedValue representation. Any record type containing a tuple-struct field routes here and hits the deliberate unimplemented!().

Source

Thrown at crates/burn-store/src/nested/de.rs:377

    }

    fn deserialize_tuple<V>(self, _len: usize, _visitor: V) -> Result<V::Value, Self::Error>
    where
        V: Visitor<'de>,
    {
        unimplemented!("deserialize_tuple is not implemented")
    }

    fn deserialize_tuple_struct<V>(
        self,
        _name: &'static str,
        _len: usize,
        _visitor: V,
    ) -> Result<V::Value, Self::Error>
    where
        V: Visitor<'de>,
    {
        unimplemented!("deserialize_tuple_struct is not implemented")
    }

    fn deserialize_enum<V>(
        self,
        _name: &'static str,
        variants: &'static [&'static str],
        visitor: V,
    ) -> Result<V::Value, Self::Error>
    where
        V: Visitor<'de>,
    {
        fn clone_unsafely<T>(thing: &T) -> T {
            unsafe {
                let mut clone = std::mem::MaybeUninit::<T>::uninit();
                let clone_ptr = clone.as_mut_ptr();
                ptr::copy_nonoverlapping(thing as *const T, clone_ptr, 1);
                clone.assume_init()
            }

View on GitHub (pinned to d16f7ba2ed)

Solutions

Convert the tuple struct to a named-field struct so it deserializes via deserialize_struct.
For single-field newtypes, ensure serde treats them as transparent and the inner type uses a supported deserialize_* method, or inline the inner value.
Use #[serde(deserialize_with)] to build the tuple struct from a supported seq/map representation.
Regenerate the checkpoint to match the supported record schema.

Example fix

// before
struct Id(u32);
struct Item { id: Id } // -> deserialize_tuple_struct panic
// after
#[derive(Deserialize)]
struct Id { value: u32 }
struct Item { id: Id }

Defensive patterns

Strategy: validation

Validate before calling

// Convert tuple structs to named-field structs:
// struct Id(u32);            // panics
// struct Id { value: u32 }   // supported via deserialize_struct

Try / catch

let record = std::panic::catch_unwind(|| from_nested_value::<MyItem>(value.clone()))
    .map_err(|_| "record contains tuple struct: not supported by nested deserializer");

Prevention

Avoid tuple structs (including multi-field wrappers) in record item types.
Prefer named-field structs so serde uses deserialize_struct.
Round-trip test records whenever wrapper types change.

When it happens

Trigger: Deserializing a Burn record that includes a tuple-struct (newtype struct with multiple fields, or any struct declared with parentheses) among its fields, via the nested-value recorder load path.

Common situations: Wrapper/newtype patterns in record items; schema refactors introducing tuple structs across Burn versions; version mismatch between saving and loading code.

Related errors

AI-assisted analysis of tracel-ai/burn@d16f7ba2ed (2026-09-05). Data as JSON: /api/errors/25a5129527dab01c. Report an issue: GitHub.