Skip to main content

​
Launch Issues

Symptom: Package 'package_name' not found or Launch file not foundCause: Launch or worlds directories are not installed in CMakeLists.txt, or workspace hasn’t been rebuilt.Solution:
1

Check CMakeLists.txt

Ensure the launch directory is installed:
install(DIRECTORY
  launch
  DESTINATION share/${PROJECT_NAME}
)
2

Rebuild the package

colcon build --symlink-install --packages-select package_name
source install/setup.bash
3

Verify installation

ros2 pkg prefix package_name
ls $(ros2 pkg prefix package_name)/share/package_name/launch
Symptom: Simulation fails to start, port already in use, or performance degradation.Cause: Previous Gazebo instances didn’t terminate cleanly.Solution:Kill all Gazebo processes:
pkill -9 -f "gz sim"
Then relaunch:
ros2 launch lunabot_simulation moon_yard.launch.py
Add this alias to your ~/.bashrc for quick access:
alias killgz='pkill -9 -f "gz sim"'
Symptom: Simulation launches but models are missing or fail to appear.Cause: First download requires internet connection. Models are cached locally after initial download.Solution:
1

Ensure internet connection

Models are downloaded from Gazebo Fuel on first launch.
2

Wait for download

Check terminal output for download progress. Large models may take several minutes.
3

Verify cache

Models are cached in ~/.gz/fuel/ for offline use:
ls ~/.gz/fuel/fuel.gazebosim.org/
After the first download, models work offline. The cache persists across launches.

​
Build Issues

Symptom: Build fails with CMake configuration errors.Solution:
1

Clean build artifacts

rm -rf build/ install/ log/
2

Reinstall dependencies

rosdep install --from-paths src -y --ignore-src
3

Rebuild workspace

colcon build --symlink-install
source install/setup.bash
Symptom: ModuleNotFoundError when launching nodes.Cause: Workspace not sourced, or package not installed correctly.Solution:
1

Source workspace

source install/setup.bash
2

Verify package installation

ros2 pkg list | grep lunabot
3

Rebuild if necessary

colcon build --symlink-install --packages-select package_name
source install/setup.bash
Always run source install/setup.bash after rebuilding, in every terminal.
Symptom: CI fails with “Missing interface” or “Type mismatch” errors.Cause: ROS topic, action, or TF link was renamed or removed without updating .github/contracts/interface_contracts.json.Solution:
1

Run contract check locally

python3 .github/scripts/check_interface_contracts.py
2

Identify missing interfaces

The script will report which interfaces are missing or have type mismatches.
3

Update contract file

Edit .github/contracts/interface_contracts.json to match your changes:
  • Update name if you renamed a topic/action
  • Update type if you changed the message type
  • Update source if you moved the interface declaration
4

Verify fix

python3 .github/scripts/check_interface_contracts.py
Should output: Interface contract check passed
Run this check before pushing to catch contract violations early.

​
Runtime Issues

Symptom: ros2 node list doesn’t show your node.Cause: Node failed to start, or entry point not registered.Solution:
1

Check terminal output

Look for Python errors or stack traces when launching.
2

Verify entry point

Check setup.py has the correct entry point:
entry_points={
    'console_scripts': [
        'your_node = package_name.your_node:main',
    ],
},
3

Rebuild and source

colcon build --symlink-install --packages-select package_name
source install/setup.bash
4

Test node directly

ros2 run package_name your_node
Symptom: ros2 topic echo /your/topic shows no data.Solution:
1

Verify topic exists

ros2 topic list
2

Check publisher info

ros2 topic info /your/topic
Should show at least one publisher.
3

Inspect node logs

ros2 run rqt_console rqt_console
Look for errors in your node’s logs.
4

Test with ros2 topic pub

ros2 topic pub /your/topic std_msgs/msg/String "data: 'test'"
Verify subscribers can receive data.
Symptom: Lookup would require extrapolation or Frame [name] does not exist.Cause: Missing TF broadcaster, incorrect frame names, or timing issues.Solution:
1

Visualize TF tree

ros2 run tf2_tools view_frames
evince frames.pdf
Check if your frames are connected.
2

Check frame names

ros2 run tf2_ros tf2_echo source_frame target_frame
3

Verify EKF config

If using robot_localization, check src/lunabot_localisation/config/ekf.yaml for correct frame names.
Frame names are case-sensitive. base_link and Base_link are different frames.

​
Simulation Performance

Symptom: Low frame rate, sluggish response, or high CPU usage.Solution:
1

Close visualization tools

Only run Rviz2, GZ Web, or Foxglove when actively debugging.
2

Kill duplicate instances

pkill -9 -f "gz sim"
Then relaunch once.
3

Reduce sensor rates

Edit sensor update rates in URDF/SDF files (requires rebuild).
The simulation is configured for headless mode by default to maximize performance.

​
Development Environment

Symptom: ros2: command not found or colcon: command not found.Cause: ROS environment not sourced.Solution:
1

Source ROS setup

source /opt/ros/humble/setup.bash
2

Add to bashrc

echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
source ~/.bashrc
3

Source workspace

source install/setup.bash
Symptom: Cannot write to directories or execute scripts.Solution:For Python scripts:
chmod +x src/package_name/scripts/your_script.py
For build artifacts:
sudo chown -R $USER:$USER build/ install/ log/

​
Getting More Help

If your issue isn’t covered here:
1

Check logs

Review terminal output and ros2 run rqt_console rqt_console for error messages.
2

Search existing issues

Visit GitHub Issues to see if others have encountered the same problem.
3

Open a new issue

If you can’t find a solution, open a new issue with:
  • System information (OS, ROS version)
  • Steps to reproduce
  • Error messages and logs
  • What you’ve already tried
4

Contact the team

Reach out to the software lead for urgent issues or questions.

Build docs developers (and LLMs) love

Get started for freeTalk to us