Skip to main content

​
“Type doesn’t implement Copy”

Problem: Your struct doesn’t implement Copy. Solution: Ensure all fields are Copy types: 
// ❌ Problem: Contains String
struct Data {
    name: String,  // Not Copy!
}

// ✅ Solution: Use fixed-size array
#[derive(Copy, Clone)]
#[repr(C)]
struct Data {
    name: [u8; 32],  // Copy!
}
Common causes:
  • Using String instead of [u8; N]
  • Using Vec<T> instead of [T; N]
  • Using HashMap or other heap-allocated collections
  • Using types with Drop implementations

​
”Serialization failed”

Problem: Type has incompatible layout or size mismatch. Solution: Add #[repr(C)] and ensure type size matches: 
// ❌ Problem: Rust layout (may have padding)
struct Data {
    value: f32,
}

// ✅ Solution: C layout
#[derive(Copy, Clone)]
#[repr(C)]
struct Data {
    value: f32,
}
Check type size: 
use std::mem;

#[derive(Copy, Clone)]
#[repr(C)]
struct MyData {
    // ... fields
}

println!("Size: {} bytes", mem::size_of::<MyData>());

​
“Invalid byte length” Error

Problem: Byte length doesn’t match the expected type size. Solution: Ensure the bytes you’re deserializing match the type size: 
// Check size before deserializing
let expected_size = std::mem::size_of::<SensorData>();
if bytes.len() != expected_size {
    eprintln!("Size mismatch: expected {} bytes, got {}", expected_size, bytes.len());
    return Err("Invalid size".into());
}

let data = SensorData::from_bytes(&bytes)?;
Common causes:
  • Truncated messages
  • Messages from different versions
  • Incorrect serialization format

​
Relocatable Message Issues

Problem: Messages wrapped in relocatable format aren’t being deserialized. Solution: from_bytes() automatically handles relocatable messages. If you’re still having issues: 
// ✅ Good: from_bytes() handles relocatable messages automatically
match SensorData::from_bytes(&bytes) {
    Ok(data) => println!("Deserialized: {:?}", data),
    Err(e) => eprintln!("Error: {}", e),
}

// ❌ Bad: Don't manually unwrap - let from_bytes() handle it
The from_bytes() implementation automatically:
  1. Checks if bytes are relocatable-wrapped
  2. Extracts the payload field if present
  3. Falls back to raw bytes if not wrapped
You don’t need to manually handle relocatable messages.

​
Type Size Too Large

Problem: Message type is very large, causing performance issues. Solution: Consider splitting into smaller messages or using a different approach: 
// ⚠️ Problem: Very large type
#[derive(Copy, Clone)]
#[repr(C)]
struct LargeData {
    buffer: [u8; 10_000_000],  // 10MB per message!
}

// ✅ Solution 1: Split into smaller messages
#[derive(Copy, Clone)]
#[repr(C)]
struct DataChunk {
    chunk_id: u32,
    data: [u8; 1024],  // 1KB chunks
}

// ✅ Solution 2: Use variable-size allocation
// (if supported by your transport)

​
Memory Layout Issues

Problem: Struct has unexpected padding or alignment. Solution: Always use #[repr(C)] to ensure C-compatible layout: 
// ❌ Problem: May have padding
#[derive(Copy, Clone)]
struct Data {
    flag: bool,      // 1 byte
    value: f64,      // 8 bytes
    // May have 7 bytes of padding between flag and value
}

// ✅ Solution: Use #[repr(C)]
#[derive(Copy, Clone)]
#[repr(C)]
struct Data {
    flag: bool,
    value: f64,
    // Padding is explicit and predictable
}

​
Cross-Language Compatibility Issues

Problem: Messages don’t deserialize correctly between languages. Solution: Use protobuf for cross-language communication: 
// ✅ Good: Use protobuf for cross-language
#[derive(Clone, PartialEq, ProstMessage)]
pub struct CrossLangData {
    #[prost(uint64, tag = "1")]
    pub timestamp: u64,
    #[prost(float, tag = "2")]
    pub temperature: f32,
}

// ❌ Bad: Copy types may not work across languages
#[derive(Copy, Clone)]
#[repr(C)]
struct RustOnlyData {
    value: f32,
}
Copy types with #[repr(C)] work well for same-language communication. For cross-language compatibility (Rust ↔ Python ↔ C++), use protobuf via the ProtoSerializable trait.

​
Deserialization Returns Wrong Values

Problem: Deserialized values don’t match what was sent. Possible causes:
  1. Endianness mismatch: Ensure consistent byte order 
    // Rust uses native endianness by default
// For network communication, consider explicit endianness
  2. Type size mismatch: Check that sender and receiver use the same type 
    // Ensure both sides use the same struct definition
  3. Field order mismatch: Ensure field order matches 
    // Fields are serialized in declaration order
// Ensure both sides have the same field order

​
Performance Issues

Problem: Serialization is too slow. Solutions:
  1. Use local transport: Local communication uses zero-copy, no serialization overhead 
    // Local transport = zero-copy, fastest
// Network transport = serialization overhead
  2. Keep types small: Smaller types serialize faster 
    // ✅ Good: Small type
struct SmallData {
    value: f32,
}

// ⚠️ Consider: Large type
struct LargeData {
    buffer: [u8; 1_000_000],
}
  3. Use Copy types: Copy types are faster than protobuf 
    // Copy types: Fast (raw bytes)
// Protobuf: Slower (encoding/decoding)

​
Debugging Tips

​
1. Check Type Size

use std::mem;

println!("Type size: {} bytes", mem::size_of::<YourType>());

​
2. Inspect Serialized Bytes

let bytes = data.to_bytes()?;
println!("Serialized bytes: {:?}", bytes);
println!("Byte length: {}", bytes.len());

​
3. Test Round-Trip

let original = YourType { /* ... */ };
let bytes = original.to_bytes()?;
let restored = YourType::from_bytes(&bytes)?;
assert_eq!(original, restored);

​
4. Verify Memory Layout

#[derive(Copy, Clone)]
#[repr(C)]
struct Test {
    a: u8,
    b: u32,
}

// Check that layout matches expectations
assert_eq!(mem::size_of::<Test>(), 8);  // 1 + 3 padding + 4

​
Next Steps

Best Practices

Learn recommended usage patterns

Supported Types

See all supported types

API Reference

Browse the complete API documentation

Copy Types

Learn about Copy type serialization