ROS 2 CLI Cheatsheet, DDS Discovery & Error Code Troubleshooting (Humble/Jazzy)
Interactive QoS/DDS compatibility checker + searchable ROS 2 CLI, TF2, DDS discovery, and ros2_control troubleshooting table.
Interactive ROS 2 QoS & DDS Env Builder
Publisher (RELIABLE / VOLATILE) satisfies Subscriber (RELIABLE / VOLATILE). Ready for deterministic topic transport.
Showing 32 of 32 ROS 2 diagnostics
| Category | Command / Error Signature | Meaning / Root Cause | Engineering Fix |
|---|---|---|---|
| CLI & Nodes | ros2 node list / info <node> | Inspect active nodes, subscribers, publishers, and services | Verify node namespace and remappings |
| CLI & Nodes | ros2 topic hz /scan | Measure real-time LiDAR or camera publish rate (Hz) | Check CPU load or USB/Ethernet bandwidth if < target Hz |
| CLI & Nodes | ros2 topic bw /camera/image_raw | Measure topic bandwidth consumption in MB/s | Switch to image_transport compressed or intra-process zero-copy |
| CLI & Nodes | ros2 topic echo <topic> –once | Print single message payload without flooding terminal | Confirm header.frame_id and header.stamp match robot clock |
| CLI & Nodes | ros2 param dump /controller_manager | Export live YAML parameter tree for debugging | Diff against bringup config YAML for typoed param names |
| CLI & Nodes | ros2 service call /trigger std_srvs/srv/Trigger | Invoke service manually from CLI | Verify server availability with ros2 service list -t |
| CLI & Nodes | ros2 action send_goal /navigate_to_pose … | Test Nav2 or MoveIt action servers directly | Check feedback stream and goal cancellation status |
| CLI & Nodes | ros2 bag record -o run1 /tf /tf_static /scan /odom | Capture deterministic sensor & TF playback bag | Add –storage mcap in Humble/Jazzy for fast random-access playback |
| CLI & Nodes | ros2 doctor –report | Audit middleware, network interfaces, and package versions | Fix WARN items on multicast or stale env variables |
| CLI & Nodes | ros2 pkg prefix <pkg_name> | Confirm workspace overlay sourced correctly | Always run source install/setup.bash in every terminal |
| DDS Discovery | RMW_IMPLEMENTATION=rmw_cyclonedds_cpp | Switch DDS middleware to CycloneDDS | Fixes Wi-Fi/multi-host discovery stalls on large PointCloud2 topics |
| DDS Discovery | ROS_DOMAIN_ID=42 | Isolate robot fleet traffic on a dedicated UDP port range | Keep IDs between 0-101; mismatched IDs cause silent empty topic lists |
| DDS Discovery | ROS_LOCALHOST_ONLY=1 (Humble) / ROS_AUTOMATIC_DISCOVERY_RANGE=LOCALHOST (Jazzy) | Confine DDS traffic to loopback interface | Prevents lab robots on same Wi-Fi from hijacking each other |
| DDS Discovery | QoS Incompatible Offer (RELIABLE vs BEST_EFFORT) | Subscriber stays silent despite topic appearing in topic list | Run ros2 topic info -v <topic> and align Reliability & Durability QoS |
| DDS Discovery | FastDDS SHM Port Lock / File Corrupt | Nodes hang at startup after SIGKILL crash | Clear /dev/shm/fastrtps_* or configure UDPv4 transport XML |
| DDS Discovery | Multicast Blocked on Linux UFW / Docker | Remote RViz2 sees no topics from robot SBC | Enable UDP multicast (ufw allow proto udp) or use Docker –net=host |
| TF2 & Transforms | Lookup would require extrapolation into the future | Node timestamp ahead of TF buffer clock | Sync clocks via chrony/NTP and verify consistent use_sim_time |
| TF2 & Transforms | Lookup would require extrapolation into the past | TF buffer too short or static broadcaster not running | Verify robot_state_publisher and increase tf2 cache_time_sec |
| TF2 & Transforms | Could not find a connection between map and base_link | Broken TF tree between AMCL/SLAM, odom, and base_link | Run ros2 run tf2_tools view_frames to inspect disconnected subtrees |
| TF2 & Transforms | ros2 run tf2_ros tf2_echo base_link laser_frame | Verify live 6-DoF translation (m) and rotation (deg/rad) | Confirm static LiDAR mounting offset matches physical CAD (mm / in) |
| TF2 & Transforms | Duplicate /tf broadcasters jittering RViz model | Two nodes publishing odom->base_link simultaneously | Disable wheel odom TF if robot_localization EKF publishes odom->base_link |
| ros2_control | Controller spawner waiting for /controller_manager | URDF missing <ros2_control> plugin tag or node crashed | Inspect controller_manager logs and verify hardware pluginlib XML |
| ros2_control | Could not switch controllers: hardware interface claimed | Two controllers attempting to command same joint velocity/position | Deactivate conflicting controller with ros2 control switch_controllers |
| ros2_control | ros2 control list_hardware_interfaces | Check claimed vs unclaimed state/command interfaces | Confirm joint names in YAML match URDF <joint name="…"> exactly |
| ros2_control | Real-time loop overrun / jitter on EtherCAT or CAN | Non-PREEMPT_RT kernel or blocking I/O inside write() | Isolate CPU core (isolcpus), enable PREEMPT_RT, and avoid heap alloc in loop |
| ros2_control | JointTrajectoryController goal aborted: path tolerance | Encoder scaling or PID gains cause following error exceedance | Tune trajectory_tolerance and verify gear ratio / ticks_per_rev |
| Nav2 & MoveIt 2 | Nav2 costmap warning: Sensor origin out of map bounds | Robot pose jumped or map origin too small | Check AMCL initial_pose and rolling_window costmap dimensions (m / ft) |
| Nav2 & MoveIt 2 | Nav2 robot spinning in place (recovery loop) | Inflation radius exceeds corridor clearance or footprint too large | Verify robot_radius / footprint (m / in) and inflation_radius margin |
| Nav2 & MoveIt 2 | MoveIt 2: Unable to sample any valid states for goal tree | Target pose outside reach, joint limits violated, or self-collision | Check SRDF disable_collisions matrix and IK solver timeout |
| Nav2 & MoveIt 2 | MoveIt 2: Controller failed with error code -4 (TOLERANCE) | Physical joint settled outside goal_time or goal_tolerance | Increase constraints/goal_time or calibrate joint zero offsets |
| Nav2 & MoveIt 2 | Gazebo Harmonic / Humble clock frozen (/clock missing) | ros_gz_bridge not bridging /clock topic | Bridge /clock@rosgraph_msgs/msg/Clock[gz.msgs.Clock and set use_sim_time:=true |
| Nav2 & MoveIt 2 | colcon build –symlink-install –cmake-args -DCMAKE_BUILD_TYPE=Release | Build ROS 2 C++ nodes with full O3 optimization | Essential for real-time PCL, SLAM, and MoveIt collision checking |
Frequently Asked Engineering Questions
Why does ros2 topic list show nothing across two Ubuntu machines?
Confirm both machines share the exact same ROS_DOMAIN_ID (0-101), UDP multicast is allowed through ufw firewall, and ROS_LOCALHOST_ONLY / ROS_AUTOMATIC_DISCOVERY_RANGE is not isolating localhost.
How do I fix TF2 Extrapolation Error into the future or past?
Synchronize system clocks using chrony/NTP across SBC and workstation, set use_sim_time consistently across all nodes, and increase transform_tolerance in Nav2 or MoveIt.
When should I switch from FastDDS to CycloneDDS in ROS 2?
If large camera/point-cloud messages stall discovery over Wi-Fi or shared-memory segments lock up after node crashes, switching RMW_IMPLEMENTATION=rmw_cyclonedds_cpp often stabilizes discovery.