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:

   // Custom router port
   let router_config = RouterConfigBuilder::new()
       .with_listen_port(7448)
       .build()?;
   
   // Connect sessions to custom port
   let ctx = ZContextBuilder::default()
       .with_router_endpoint("tcp/localhost:7448")
       .build()?;

Solution: Use peer mode with multicast discovery:

let ctx = ZContextBuilder::default()
    .with_zenoh_config(zenoh::Config::default())
    .build()?;

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