Root Cause: ROS 2 environment not sourced or packages not installed.

Solutions:

1. Source ROS 2 environment:

   source /opt/ros/jazzy/setup.bash
   # or for rolling:
   source /opt/ros/rolling/setup.bash
   

2. Verify environment variables:

   echo $AMENT_PREFIX_PATH
   echo $CMAKE_PREFIX_PATH
   

3. Check package installation:

   ros2 pkg prefix example_interfaces
   # If fails, install:
   sudo apt install ros-jazzy-example-interfaces
   

4. Clean and rebuild:

   cargo clean -p ros-z-msgs
   cargo build -p ros-z-msgs
   

Common Error Messages:

Root Cause: ros-z-msgs is not part of default workspace members.

Solution:

# Build ros-z-msgs explicitly
cargo build -p ros-z-msgs

# Then build your example
cargo build --example z_srvcli

Note: ros-z-msgs is excluded from default builds to avoid requiring ROS 2 for core development. Build it explicitly when needed.

Solutions:

# Use parallel builds (automatic on most systems)
cargo build -j $(nproc)

# Build only what you need
cargo build -p ros-z-msgs --features std_msgs,geometry_msgs

Solution:

# Clear cache and rebuild
cargo clean
source /opt/ros/jazzy/setup.bash
cargo build -p rcl-z

Warning: After changing feature flags or updating ROS 2, run cargo clean -p ros-z-msgs to force message regeneration.

Root Cause: Zenoh router not running or nodes not configured correctly.

Solution:

1. Ensure the router is running:

   cargo run --example zenoh_router
   

2. Verify endpoint matches in your code:

   let ctx = ZContextBuilder::default()
       .with_router_endpoint("tcp/localhost:7447")?  // Must match router
       .build()?;

Root Cause: Another process is using port 7447.

Solutions:

1. Stop the conflicting process

2. Use a custom port:

   Start the router on a different port:

   cargo run --example zenoh_router -- --listen "tcp/[::]:7448"
   

   Then connect your sessions to that port:

   let ctx = ZContextBuilder::default()
       .with_router_endpoint("tcp/localhost:7448")?
       .build()?;

Solution: Use peer mode with multicast discovery:

let ctx = ZContextBuilder::default()
    .with_mode("peer")
    .build()?;

Warning: Peer mode won't interoperate with ROS 2 nodes using rmw_zenoh_cpp in router mode.

Symptom: Publisher publishes to /robot/sensors/camera but subscriber never receives messages.

Root Cause: Old versions of ros-z (before 0.1.0) incorrectly mangled slashes in topic key expressions, breaking multi-segment topic routing.

Solution: Update to ros-z 0.1.0+ which correctly preserves internal slashes in topic key expressions.

Verify the fix:

# Enable debug logging to see key expressions
RUST_LOG=ros_z=debug cargo run --example z_pubsub

Look for key expressions in the output:

Technical Details:

• Topic key expressions should use strip_slashes(): removes leading/trailing slashes, preserves internal slashes
• Liveliness tokens should use mangle_name(): replaces all / with %
• This matches the behavior of rmw_zenoh_cpp

See Key Expression Formats for details.

Root Cause: Type hash mismatch — ros-z and the ROS 2 node disagree on the message definition's RIHS01 hash.

Diagnosis:

Enable debug logging to see the key expressions being advertised:

RUST_LOG=ros_z=debug cargo run --example z_pubsub

Look for the hash in the key expression output:

[PUB] Key expression: 0/chatter/std_msgs::msg::dds_::String_/RIHS01_<hash>

Compare the RIHS01_<hash> with what the ROS 2 node advertises (visible with ZENOH_LOGS=debug on the ROS 2 side). If the hashes differ, the nodes will not exchange messages.

Common causes:

Verify the correct type:

ros2 interface show std_msgs/msg/String

Then check that ros-z-codegen/assets/jazzy/std_msgs/msg/String.msg matches exactly.