Skip to main content
Troubleshoot Gazebo Harmonic simulator issues in the TurtleBot3 environment.

​
Gazebo won’t start

Symptoms:
  • tb3_empty command does nothing
  • Error messages in terminal
Old Gazebo processes may prevent new ones from starting:
pkill -9 gz
pkill -9 gzserver
pkill -9 gzclient
tb3_empty
Test if OpenGL rendering is working:
# Test OpenGL
glxinfo | grep "direct rendering"
# Should say "Yes"
If it says “No”, use software rendering:
export LIBGL_ALWAYS_SOFTWARE=1
tb3_empty

echo $TURTLEBOT3_MODEL
# Should output: burger

# Set if empty:
export TURTLEBOT3_MODEL=burger
This variable must be set for TurtleBot3 launch files to work.
See detailed error messages:
ros2 launch turtlebot3_gazebo empty_world.launch.py --verbose
This shows all ROS2 node output and can help identify the specific failure.

​
No robot model in Gazebo

Symptoms:
  • Gazebo opens but is empty
  • No TurtleBot3 appears
The TURTLEBOT3_MODEL environment variable must be set for the robot to spawn. Always verify this first.
1

Verify model variable

echo $TURTLEBOT3_MODEL
# Must output: burger, waffle, or waffle_pi

export TURTLEBOT3_MODEL=burger
2

Check package installation

ros2 pkg list | grep turtlebot3

# If missing packages, rebuild:
cd /workspace/turtlebot3_ws
colcon build --symlink-install
source install/setup.bash
3

Source workspace

source /opt/ros/jazzy/setup.bash
source /workspace/turtlebot3_ws/install/setup.bash
# Or use: sb

​
Gazebo crashes

If Gazebo crashes or closes unexpectedly:
GPU acceleration issues can cause crashes:
export LIBGL_ALWAYS_SOFTWARE=1
tb3_empty
Examine log files for error details:
cat ~/.gz/gazebo/server.log
cat ~/.gz/gazebo/client.log
cat /workspace/turtlebot3_ws/log/latest*/events.log
Corrupted cache can cause crashes:
rm -rf ~/.gz/
tb3_empty
This removes all Gazebo configuration and cache files. They’ll be regenerated on next launch.

​
Gazebo performance issues

See the Performance optimization guide for Gazebo-specific performance tips. Key solutions:
  • Allocate more resources to Docker
  • Use simpler worlds (tb3_empty vs tb3_house)
  • Enable software rendering if GPU acceleration is unstable
  • Disable shadows and reduce graphics quality in Gazebo settings

​
ROS-Gazebo bridge issues

If Gazebo runs but ROS2 topics aren’t available: 
# Check if bridge node is running
ros2 node list | grep bridge

# Verify topics are published
ros2 topic list

# Check for error messages in bridge node
ros2 node info /ros_gz_bridge
If the bridge isn’t running, check that ros-jazzy-ros-gz packages are installed: 
sudo apt install ros-jazzy-ros-gz

Build docs developers (and LLMs) love

Get started for freeTalk to us