Enable headless mode on ROS2 Humble#157
Open
griffinaddison wants to merge 1 commit intoros-controls:mainfrom
Open
Enable headless mode on ROS2 Humble#157griffinaddison wants to merge 1 commit intoros-controls:mainfrom
griffinaddison wants to merge 1 commit intoros-controls:mainfrom
Conversation
Two fixes for headless mode on Humble:
1. Add ROS_DISTRO_HUMBLE cmake define. The #if ROS_DISTRO_HUMBLE guard
for get_hardware_info() already exists in the header (line 114 of
mujoco_system_interface.hpp) but was never activated because the
cmake define wasn't set. This caused the headless hardware param
to not be read on Humble, falling through to GLFW which crashes
on headless machines (e.g., Jetson).
2. Add MUJOCO_HEADLESS environment variable fallback. On Humble, the
hardware_parameters map population from URDF <param> tags can be
unreliable. The env var provides a robust alternative:
MUJOCO_HEADLESS=1 ros2 launch ...
Tested on Jetson AGX Orin (aarch64, Ubuntu 22.04, ROS2 Humble) with
MuJoCo 3.6.0. Both arms initialize correctly in headless mode.
saikishor
requested changes
Mar 28, 2026
Member
saikishor
left a comment
saikishor
left a comment
There was a problem hiding this comment.
I don't think there is an issue with the Humble part as we also have the CI to test it. Can you walk me through the process of how you found this issue?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes headless mode on ROS2 Humble, which currently silently fails and falls through to GLFW (crashing on headless machines like Jetson).
Two small changes:
ROS_DISTRO_HUMBLEcmake define. The#if ROS_DISTRO_HUMBLEguard forget_hardware_info()already exists in the header but was never activated.MUJOCO_HEADLESSenvironment variable fallback for cases where the URDF hardware param path is unreliable on Humble.Problem
On Humble,
get_hardware_info()doesn't exist inhardware_interface::SystemInterface. The header already has a compatibility shim at line 114:But
ROS_DISTRO_HUMBLEwas never defined in cmake, so this shim is dead code. Without it, theheadlesshardware parameter can't be read, and the plugin always takes the GLFW path — crashing on headless machines.Testing
Tested on Jetson AGX Orin (aarch64, Ubuntu 22.04, ROS2 Humble, MuJoCo 3.6.0):
ERROR: could not initialize GLFW→ process diesRunning in HEADLESS mode.→ robot initializes, controllers activateChanges
mujoco_ros2_control/CMakeLists.txt: +5 lines (detect Humble, set define)mujoco_ros2_control/src/mujoco_system_interface.cpp: +4 lines (env var fallback)🤖 Generated with Claude Code