You're reading the documentation for a development version. For the latest released version, please have a look at Jazzy.
Installation troubleshooting
Troubleshooting techniques for installation are sorted by the platforms they apply to.
General
General troubleshooting techniques apply to all platforms.
Enable multicast
In order to communicate successfully via DDS, the used network interface has to be multicast enabled. We’ve seen in past experiences that this might not necessarily be enabled by default (on Ubuntu or OSX) when using the loopback adapter. See the original issue or a conversation on ros-answers. You can verify that your current setup allows multicast with the ROS 2 tool:
In Terminal 1:
ros2 multicast receive
In Terminal 2:
ros2 multicast send
If the first command did not return a response similar to:
Received from xx.xxx.xxx.xx:43751: 'Hello World!'
then you will need to update your firewall configuration to allow multicast using ufw.
sudo ufw allow in proto udp to 224.0.0.0/4
sudo ufw allow in proto udp from 224.0.0.0/4
You can check if the multicast flag is enabled for your network interface using the ifconfig tool and looking for MULITCAST in the flags section:
eno1: flags=4163<...,MULTICAST>
...
Import failing without library present on the system
Sometimes rclpy fails to be imported because the expected C extension libraries are not found.
If so, compare the libraries present in the directory with the one mentioned in the error message.
Assuming a file with a similar name exists (same prefix like _rclpy. and same suffix like .so but a different Python version / architecture) you are using a different Python interpreter than which was used to build the C extension.
Be sure to use the same Python interpreter as the one used to build the binary.
For example, such a mismatch can crop up after an update of the OS. Then, rebuilding the workspace may fix the issue.
Linux
Internal compiler error
If you experience an ICE when trying to compile on a memory constrained platform like a Raspberry PI you might want to build single threaded (prefix the build invocation with MAKEFLAGS=-j1).
Out of memory
The ros1_bridge in its current form requires 4Gb of free RAM to compile.
If you don’t have that amount of RAM available it’s suggested to use COLCON_IGNORE in that folder and skip its compilation.
Multiple host interference
If you’re running multiple instances on the same network you may get interference.
To avoid this you can set the environment variable ROS_DOMAIN_ID to a different integer, the default is zero.
This will define the DDS domain id for your system.
Exception sourcing setup.bash
If you encounter exceptions when trying to source the environment after building from source, try to upgrade colcon related packages using
colcon version-check # check if newer versions available
sudo apt install python3-colcon* --only-upgrade # upgrade installed colcon packages to latest version
Anaconda Python Conflict
conda does not work in conjunction with ROS 2.
Make sure that your PATH environment variable does not have any conda paths in it.
You may have to check your .bashrc for this line and comment it out.
Cannot start rviz2
rviz2 may fail to start on a Wayland display system with errors like:
QSocketNotifier: Can only be used with threads started with QThread
[INFO] [1714730141.758659580] [rviz2]: Stereo is NOT SUPPORTED
[INFO] [1714730141.758813709] [rviz2]: OpenGl version: 3.1 (GLSL 1.4)
[ERROR] [1714730141.797879232] [rviz2]: rviz::RenderSystem: error creating render window: RenderingAPIException: Invalid parentWindowHandle (wrong server or screen) in GLXWindow::create at ./.obj-aarch64-linux-gnu/ogre_vendor-prefix/src/ogre_vendor/RenderSystems/GLSupport/src/GLX/OgreGLXWindow.cpp (line 246)
...
[ERROR] [1714730141.808124283] [rviz2]: Unable to create the rendering window after 100 tries
terminate called after throwing an instance of 'std::runtime_error'
what(): Unable to create the rendering window after 100 tries
Aborted (core dumped)
This is due to an incompatibility between Wayland and RViz2. You may be able to workaround this problem by running RViz2 in X11 compatibility mode:
QT_QPA_PLATFORM=xcb rviz2
macOS
Segmentation fault when using pyenv
pyenv seems to default to building Python with .a files, but that causes issues with rclpy, so it’s recommended to build Python with Frameworks enabled on macOS when using pyenv:
Library not loaded; image not found
If you are seeing library loading issues at runtime (either running tests or running nodes), such as the following:
ImportError: dlopen(.../ros2_<distro>/ros2-osx/lib/python3.7/site-packages/rclpy/_rclpy.cpython-37m-darwin.so, 2): Library not loaded: @rpath/librcl_interfaces__rosidl_typesupport_c.dylib
Referenced from: .../ros2_<distro>/ros2-osx/lib/python3.7/site-packages/rclpy/_rclpy.cpython-37m-darwin.so
Reason: image not found
Then you probably have System Integrity Protection enabled. Follow these instructions to disable System Integrity Protection (SIP).
Qt build error: unknown type name 'Q_ENUM'
If you see build errors related to Qt, e.g.:
In file included from /usr/local/opt/qt/lib/QtGui.framework/Headers/qguiapplication.h:46:
/usr/local/opt/qt/lib/QtGui.framework/Headers/qinputmethod.h:87:5: error:
unknown type name 'Q_ENUM'
Q_ENUM(Action)
^
you may be using qt4 instead of qt5: see https://github.com/ros2/ros2/issues/441
Missing symbol when opencv (and therefore libjpeg, libtiff, and libpng) are installed with Homebrew
If you have opencv installed you might get this:
dyld: Symbol not found: __cg_jpeg_resync_to_restart
Referenced from: /System/Library/Frameworks/ImageIO.framework/Versions/A/ImageIO
Expected in: /usr/local/lib/libJPEG.dylib
in /System/Library/Frameworks/ImageIO.framework/Versions/A/ImageIO
/bin/sh: line 1: 25274 Trace/BPT trap: 5 /usr/local/bin/cmake
If so, to build you’ll have to do this:
$ brew unlink libpng libtiff libjpeg
But this will break opencv, so you’ll also need to update it to continue working:
$ sudo install_name_tool -change /usr/local/lib/libjpeg.8.dylib /usr/local/opt/jpeg/lib/libjpeg.8.dylib /usr/local/lib/libopencv_highgui.2.4.dylib
$ sudo install_name_tool -change /usr/local/lib/libpng16.16.dylib /usr/local/opt/libpng/lib/libpng16.16.dylib /usr/local/lib/libopencv_highgui.2.4.dylib
$ sudo install_name_tool -change /usr/local/lib/libtiff.5.dylib /usr/local/opt/libtiff/lib/libtiff.5.dylib /usr/local/lib/libopencv_highgui.2.4.dylib
$ sudo install_name_tool -change /usr/local/lib/libjpeg.8.dylib /usr/local/opt/jpeg/lib/libjpeg.8.dylib /usr/local/Cellar/libtiff/4.0.4/lib/libtiff.5.dylib
The first command is necessary to avoid things built against the system libjpeg (etc.) from getting the version in /usr/local/lib. The others are updating things built by Homebrew so that they can find the version of libjpeg (etc.) without having them in /usr/local/lib.
Xcode-select error: tool xcodebuild requires Xcode, but active developer directory is a command line instance
If you recently installed Xcode, you may encounter this error:
Xcode: xcode-select: error: tool 'xcodebuild' requires Xcode,
but active developer directory '/Library/Developer/CommandLineTools' is a command line tools instance
To resolve this error, you will need to:
Double check that you have the command line tool installed:
$ xcode-select --install
Accept the terms and conditions of Xcode by typing in terminal:
$ sudo xcodebuild -license accept
Ensure Xcode app is in the
/Applicationsdirectory (NOT/Users/{user}/Applications)Point
xcode-selectto the Xcode app Developer directory using the following command:
$ sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
rosdep install error homebrew: Failed to detect successful installation of [qt5]
While following the Creating a workspace tutorial, you might encounter the following error stating that rosdep failes to install Qt5.
$ rosdep install -i --from-path src --rosdistro rolling -y
executing command [brew install qt5]
Warning: qt 5.15.0 is already installed and up-to-date
To reinstall 5.15.0, run `brew reinstall qt`
ERROR: the following rosdeps failed to install
homebrew: Failed to detect successful installation of [qt5]
This error seems to stem from a linking issue and can be resolved by running the following command.
$ cd /usr/local/Cellar
$ sudo ln -s qt qt5
Running the rosdep command should now execute normally:
$ rosdep install -i --from-path src --rosdistro rolling -y
#All required rosdeps installed successfully
Windows
Import failing even with library present on the system
Sometimes rclpy fails to be imported because of some missing DLLs on your system.
If so, make sure to install all the dependencies listed in the “Installing prerequisites” sections of the installation instructions).
If you are installing from binaries, you may need to update your dependencies: they must be the same version as those used to build the binaries.
If you are still having issues, you can use the Dependencies tool to determine which dependencies are missing on your system.
Use the tool to load the corresponding .pyd file, and it should report unavailable DLL modules.
Be sure that the current workspace is sourced before you execute the tool, otherwise there will be unresolved ROS DLL files.
Use this information to install additional dependencies or adjust your path as necessary.
CMake error setting modification time
If you run into the CMake error file INSTALL cannot set modification time on ... when installing files it is likely that an anti virus software or Windows Defender are interfering with the build. E.g. for Windows Defender you can list the workspace location to be excluded to prevent it from scanning those files.
260 character path limit
The input line is too long.
The syntax of the command is incorrect.
Depending on your directory hierarchy, you may see path length limit errors when building ROS 2 from source or your own libraries.
To allow deeper path lengths:
Run regedit.exe, navigate to Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem, and set LongPathsEnabled to 0x00000001 (1).
Hit the windows key and type Edit Group Policy.
Navigate to Local Computer Policy > Computer Configuration > Administrative Templates > System > Filesystem.
Right click Enable Win32 long paths, click Edit.
In the dialog, select Enabled and click OK.
Close and open your terminal to reset the environment and try building again.
CMake packages unable to find asio, tinyxml2, tinyxml, or eigen
We’ve seen that sometimes the chocolatey packages for asio, tinyxml2, etc. do not add important registry entries and CMake will be unable to find them when building ROS 2.
We’ve not yet been able to identify the root cause, but uninstalling the chocolatey packages (with -n if the uninstall fails the first time), and then reinstalling them will fix the issue.
patch.exe opens a new command window and asks for administrator
This will also cause the build of packages which need to use patch to fail, even you allow it to use administrator rights.
choco uninstall patch; colcon build --cmake-clean-cache- This is a bug in the GNU Patch For Windows package. If this package is not installed, the build process will instead use the version of Patch distributed with git.
Failed to create process
If running a ROS binary gives the error:
| failed to create process.
It is likely the Python interpreter was not found.
For each executable, the shebang (first line) of the accompanying script is used, so make sure Python is available under the expected path (default: C:\Python38\).
Binary installation specific
If your example does not start because of missing DLLs, please verify that all libraries from external dependencies such as OpenCV are located inside your
PATHvariable.If you forget to call the
local_setup.batfile from your terminal, the demo programs will most likely crash immediately.
Running RViz with WSL2
If you are using WSL2 to run ROS 2 on Windows, you may run into an issue running RViz that looks like:
$ rviz2
[INFO] [1695823660.091830699] [rviz2]: Stereo is NOT SUPPORTED
[INFO] [1695823660.091943524] [rviz2]: OpenGl version: 4.1 (GLSL 4.1)
D3D12: Removing Device.
Segmentation fault
One possible solution to this is to force RViz to use software rendering:
$ export LIBGL_ALWAYS_SOFTWARE=true
$ rviz2
[INFO] [1695823660.091830699] [rviz2]: Stereo is NOT SUPPORTED