Skip to main content

​
Troubleshooting

This page covers common issues, error messages, and debugging tips for Cerulion Core.

​
Common Issues

Problem: Your struct doesn’t implement Copy, so it can’t be used with Cerulion Core’s automatic serialization.Solution: Ensure all fields are Copy types:
// ❌ Problem: Contains String
struct Data {
    name: String,  // Not Copy!
}

// ✅ Solution: Use fixed-size array
#[repr(C)]
struct Data {
    name: [u8; 32],  // Copy!
}
See the Serialization page for details on Copy types.
Problem: Type has incompatible memory layout.Solution: Add #[repr(C)] to ensure C-compatible layout:
// ❌ Problem: Rust layout (may have padding)
struct Data {
    value: f32,
}

// ✅ Solution: C layout
#[repr(C)]
struct Data {
    value: f32,
}
Problem: Generated code file path is incorrect.Solution: Use OUT_DIR environment variable:
// ✅ Correct: Uses OUT_DIR
include!(concat!(env!("OUT_DIR"), "/sensor_data_generated.rs"));

// ❌ Wrong: Hard-coded path
include!("target/debug/sensor_data_generated.rs");
See the Code Generation page for details.
Problem: YAML syntax error in schema file.Solution: Validate YAML syntax:
# Check YAML syntax
yamllint schemas/your_schema.yaml
Common issues:
  • Missing colons after field names
  • Incorrect indentation
  • Invalid type names
Problem: Multiple publishers/subscribers for the same topic use different message types.Solution: Ensure all publishers/subscribers for a topic use the same type:
// First registration establishes the type
let pub1 = Publisher::<SensorData>::create("topic")?;

// This will fail - type mismatch!
let pub2 = Publisher::<DifferentType>::create("topic")?;
// Error: "Type mismatch for topic 'topic'"
Problem: Subscriber doesn’t receive messages.Possible causes:
  1. Publisher dropped before subscriber created
  2. Wrong topic name
  3. Network transport not enabled (for remote subscribers)
  4. Subscriber using wrong transport mode
Solutions:
// ✅ Good: Publisher stays alive
let publisher = Publisher::<T>::create("topic")?;
// ... keep publisher in scope ...
let subscriber = Subscriber::<T>::create("topic", None)?;

// ❌ Bad: Publisher dropped too early
{
    let publisher = Publisher::<T>::create("topic")?;
} // Publisher dropped here
let subscriber = Subscriber::<T>::create("topic", None)?;
// Subscriber won't receive messages
Problem: Local communication is slower than expected.Possible causes:
  1. Message type is not Copy
  2. Message size is very large
  3. System is under heavy load
Solutions:
  • Ensure message type implements Copy
  • Reduce message size or batch messages
  • Check system load and CPU usage
See the Performance page for optimization tips.
Problem: Network subscribers don’t receive messages.Possible causes:
  1. Network transport not enabled
  2. Network connectivity issues
  3. Subscriber not connected
  4. Firewall blocking Zenoh ports
Solutions:
// ✅ Good: Force network mode for remote subscriber
let subscriber = Subscriber::<T>::create("topic", Some(true))?;

// Check network connectivity
// Verify Zenoh ports are open
// Check logs for network errors
Network errors are logged but don’t propagate. Check logs if network communication isn’t working. Local communication continues even if the network is down.
Problem: MCAP recorder created but no messages logged.Solution: Keep recorder alive and ensure logging is enabled:
// ✅ Good: Keep recorder in scope
let recorder = Arc::new(McapRecorder::create("log.mcap", None, None)?);
publisher.enable_mcap_logging(recorder.clone());
// ... send messages ...
// Recorder closes when dropped (at end of scope)

// ❌ Bad: Recorder dropped too early
{
    let recorder = Arc::new(McapRecorder::create("log.mcap", None, None)?);
    publisher.enable_mcap_logging(recorder.clone());
} // Recorder dropped here
publisher.send(data)?;  // Not logged!
Problem: Cerulion Core uses too much CPU.Possible causes:
  1. Very high message rate
  2. Large message sizes
  3. Multiple background threads
Solutions:
  • Reduce message rate if possible
  • Reduce message size
  • Use TopicManager to share sessions (reduces thread count)
See the Performance page for details.

​
Error Messages

​
”Type mismatch for topic ‘topic’”

Meaning: Multiple publishers/subscribers for the same topic use different message types. Solution: Ensure all publishers/subscribers for a topic use the same type. The first registration establishes the type.

​
”Failed to create publisher”

Possible causes:
  • Topic name is invalid
  • iceoryx2 initialization failed
  • Zenoh session creation failed
Solution: Check system logs for detailed error messages. Verify iceoryx2 and Zenoh are properly installed.

​
”Failed to create subscriber”

Possible causes:
  • Topic name is invalid
  • No publisher exists (for local transport)
  • Network transport unavailable (for network-only mode)
Solution: Ensure a publisher exists for local transport, or use Some(true) to force network transport.

​
”Serialization failed”

Meaning: Message type cannot be serialized. Possible causes:
  • Type doesn’t implement Copy
  • Type has incompatible memory layout
  • Type contains non-serializable fields (String, Vec, etc.)
Solution: Ensure message type implements Copy and has #[repr(C)] layout. See the Serialization page.

​
Debugging Tips

​
1. Enable Verbose Logging

// Set RUST_LOG environment variable
// RUST_LOG=debug cargo run

// Or in code
env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("debug")).init();
Verbose logging shows detailed information about publisher/subscriber creation, message sending, and network operations.

​
2. Check Message Reception

// Add logging to verify messages are received
if let Ok(Some(data)) = subscriber.receive() {
    println!("Received message: {:?}", data);
} else {
    println!("No message available");
}

​
3. Verify Transport Mode

// Check if local transport is available
let manager = TopicManager::create()?;
if manager.check_local_availability("topic") {
    println!("Local transport available");
} else {
    println!("Local transport not available, using network");
}

​
4. Monitor Network Status

// Check if network is enabled (for publishers)
// Note: This requires access to internal publisher state
// For now, check logs for network errors
Network errors are logged but don’t propagate. Check application logs for network-related errors.

​
5. Profile Performance

use std::time::Instant;

let start = Instant::now();
publisher.send(data)?;
let elapsed = start.elapsed();
println!("Send took: {:?}", elapsed);

​
Getting Help

If you’re still experiencing issues:
  1. Check the documentation: Review relevant pages for your issue
  2. Review error messages: Error messages often contain helpful information
  3. Check system logs: Look for detailed error messages in application logs
  4. Verify installation: Ensure iceoryx2 and Zenoh are properly installed
  5. Test with simple example: Try the Quick Start example to verify basic functionality

​
Next Steps

Quick Start

Verify basic functionality with a simple example

Serialization

Understand Copy types and serialization requirements

Performance

Optimize performance and reduce latency

Architecture

Understand how components work together