Skip to content

Simulation

Troubleshooting Banner

Simulation Troubleshooting#

Gazebo window is black or shows EGL / DRI rendering errors#

Symptom: Gazebo opens but the viewport is black, or the terminal shows errors about libEGL, DRI, or Mesa.

Cause: The system is missing the Mesa DRI OpenGL driver.

Fix:

sudo apt-get install libgl1-mesa-dri

If running inside Docker or a headless environment, use headless:=true to disable the Gazebo GUI entirely.

Robot does not appear in Gazebo#

Symptom: Gazebo launches and the world loads, but the Micipsa robot model is not visible.

Cause: /robot_description was not published before the spawner ran. The spawner reads the robot model from that topic at startup, if it is not available, spawning silently fails or times out.

Fix: Confirm micipsa_description is running and the parameter is populated before launching this package:

ros2 param get /robot_state_publisher robot_description | head -3

Bridged topics are missing after launch#

Symptom: ros2 topic list does not show /scan, /front_camera/color/image_raw, or other expected topics.

Cause: Either ros_gz_bridge failed to start, or the Gazebo sensor plugins have not yet started publishing on the expected Gazebo topic names.

Fix: Check the ros_gz_bridge node is running:

ros2 node list | grep ros_gz_bridge

Verify the Gazebo topic names used in gz_bridge.yaml match what Gazebo is actually publishing by listing Gazebo topics from a terminal with the Gazebo environment sourced:

gz topic -l

If there is a name mismatch between the gz_topic_name in gz_bridge.yaml and the actual Gazebo topic, update gz_bridge.yaml and rebuild.

/scan QoS mismatch with downstream nodes#

Symptom: A downstream node (SLAM Toolbox, Nav2) warns about QoS incompatibility on /scan or does not receive scan data.

Cause: /scan is published with BEST_EFFORT reliability (set explicitly in gazebo_launch.py). Downstream nodes configured with RELIABLE reliability will not receive messages from a BEST_EFFORT publisher.

Fix: Configure the downstream node to use BEST_EFFORT reliability for its /scan subscription, or change the QoS override in gazebo_launch.py to RELIABLE and rebuild. Note that RELIABLE over a lossy channel may cause backpressure.

Custom world file not found by Gazebo#

Symptom: Gazebo starts but loads a blank scene or logs Failed to find world file.

Cause: The path passed to gazebo_world does not exist, or the file is not reachable from the GZ_SIM_RESOURCE_PATH.

Fix: Use an absolute path when passing a custom world:

ros2 launch micipsa_simulation gazebo_launch.py \
  simulation_world_file:=$(realpath path/to/your/custom.world)