# ROS 2 CLI Cheatsheet, DDS Discovery & Error Code Troubleshooting \(Humble/Jazzy\)

> Search 34+ ROS 2 Humble/Jazzy CLI commands, FastDDS vs CycloneDDS discovery fixes, TF2 extrapolation errors, QoS checker, and ros2\_control diagnostics.

Canonical: https://roboticsengineering.in/ros2-error-codes-cli-cheatsheet-troubleshooting/ | Published: 2026-11-20 | Updated: 2026-11-20

ROS 2 Humble / Jazzy · Global Reference Hub

## 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.

COMPATIBLE — Stream Active

### Interactive ROS 2 QoS & DDS Env Builder

Publisher Reliability

Subscriber Reliability

Pub Durability

Sub Durability

DDS Middleware (RMW)

ROS_DOMAIN_ID (0–101)

export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp && export ROS_DOMAIN_ID=10

Publisher (RELIABLE / VOLATILE) satisfies Subscriber (RELIABLE / VOLATILE). Ready for deterministic topic transport.

Search Command, Error Message, or Fix

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 |

`<iframe src="https://roboticsengineering.in/ros2-error-codes-cli-cheatsheet-troubleshooting/" width="100%" height="780" style="border:1px solid #d6dfeb;border-radius:12px;" loading="lazy" title="ROS 2 CLI Cheatsheet, DDS Discovery & Error Code Troubleshooting (Humble/Jazzy)"></iframe>`

**Grow Your Robotics / Automation Brand Online with Jaadu Digital** Technical SEO, B2B lead generation, and engineering content systems built for robotics integrators and OEMs.

[Explore Jaadu Digital →](https://jaadudigital.com/)

### 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.
