Troubleshoot ROS 2 Discovery Issues in Virtual Environments

R2026b

This topic explains how to diagnose ROS 2 communication failures between MATLAB^® and remote nodes by verifying network adapter modes for WSL 2, Docker, and virtual machine environments, clearing stale ROS 2 processes, and running a publisher-subscriber diagnostic to isolate whether the failure affects outgoing messages, incoming messages, or both. You also verify that the ROS 2 distribution, ROS_DOMAIN_ID, and ROS middleware implementation (RMW_IMPLEMENTATION) match between MATLAB and the external ROS 2 environment.

Problem

When MATLAB is unable to discover or communicate with ROS 2 nodes running on a remote machine or inside a virtualized environment (WSL 2, Docker, or a virtual machine), the root cause is typically an incompatible network adapter configuration, residual node processes from a previous session, or mismatched environment variables such as the ROS_DOMAIN_ID or middleware implementation.

These issues commonly occur when you first set up communication between MATLAB and an external ROS 2 environment, or after changing your virtualization or network configuration.

Possible Solutions

Set Correct Network Adapter Mode

The network adapter mode of your virtual environment directly affects whether DDS discovery packets can reach MATLAB. Use one of the recommended networking modes for your environment:

ROS 2 Environment	Recommended Networking Mode	References to Change Networking Mode
WSL 2	NAT	Configure WSL Settings
Docker (operating in WSL 2)	Host Network	Configure Docker Settings
VirtualBox/VMWare	Bridged (recommended)/NAT	Configure Virtual Machine Settings

If your environment uses a mode other than the one recommended above, switch to the recommended mode and retry communication before continuing with the remaining diagnostic steps.

Check Network Connectivity between Host and External Environment

Make sure that the environment running ROS 2 (WSL 2, Docker, or a virtual machine) communicates with the computer where MATLAB is installed.

Find the IP address of the external ROS 2 environment. Open a terminal inside the environment and run:
```
ifconfig
```
Test the connection from the host. On your host, open a command prompt or terminal and run:
```
ping <ROS2_IP_address>
```

Ensure you are able to ping the ROS 2 environment before proceeding to test communication between MATLAB and the external ROS 2 environment.

Clean Communication Environment and Verify Two-Way Communication

Stale node processes from a previous MATLAB session or from a failed application can block new connections or cause unexpected discovery behavior. Before running any diagnostic test, ensure that no residual processes remain.

In the MATLAB command window, run this command to clear all node objects.
```
clear all;
```
On Windows^®, manually stop all applications that are failing to communicate. To achieve this, stop any remaining libmwros2server.exe from Task Manager.
Stop all ROS 2 nodes running outside MATLAB.

After cleaning the environment, verify two-way communication between MATLAB and the external ROS 2 system using the following steps.

Verify outgoing messages from MATLAB.
1. Run the following commands in the MATLAB command window to create a ROS 2 node and publisher. Send messages on the /hello_world topic and verify that they appear in the external environment.
  node = ros2node("my_node"); pub = ros2publisher(node,"/hello_world","std_msgs/String"); msg = ros2message(pub); for ii=1:100 send(pub,msg); pause(1); end
2. On the remote system, open the terminal and run the following command to subscribe to the published topic.
```
# For Unix
source /opt/ros/<distro>/setup.bash
ros2 daemon stop
ros2 topic echo /hello_world
```
  If you see messages printed in the terminal, MATLAB successfully communicates with the external ROS 2 environment.
Verify incoming messages to MATLAB.
1. On the remote system, open the terminal and create a publisher to publish from the external ROS 2 environment on the /hello_world topic.
```
# For Unix
source /opt/ros/<distro>/setup.bash
ros2 topic pub -r 10 /hello_world std_msgs/msgs/String "{data: 'hello world'}"
```
2. In the system running MATLAB, create a ROS 2 node and subscribe to the published message using the following command.
  node = ros2node('my_node'); sub = ros2subscriber(node, '/hello_world', 'std_msgs/String'); sub.LatestMessage

If MATLAB displays the incoming message, it confirms two-way communication. You can now relaunch your application to check that the communication issue is resolved. If the issue persists, continue with the next diagnostic step.

Clear Stale Fast DDS Shared Memory Files

Fast DDS stores shared memory files in the local file system to manage inter-process communication. Normally, these files are cleaned up automatically when the application closes properly. However, if MATLAB or Simulink closes unexpectedly, the cleanup routines are not executed, leaving stale shared memory files on the system. These files can prevent new Fast DDS processes from initializing communication channels, causing MATLAB to become unresponsive when you use ROS 2 features.

To resolve this issue, use one of the following workarounds.

Clean Up Shared Memory Files Manually

In the MATLAB command window, run the following command to clear resources:
```
clear all;
```
Navigate to the following path:
```
C:\ProgramData\eprosima\fastrtps_interprocess
```
Delete all contents inside this folder.
In the MATLAB command window, run the following command to clear resources and avoid conflicts:
```
clear all;
```

Disable Shared Memory Transport

In the MATLAB command window, run the following command to clear resources:
```
clear all;
```
Create a file named fastdds.xml.

Copy and paste the following XML content into the file.

<?xml version="1.0" encoding="UTF-8" ?>
<profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles" >
    <transport_descriptors>
        <transport_descriptor>
            <transport_id>UdpTransport</transport_id>
            <type>UDPv4</type>
        </transport_descriptor>
    </transport_descriptors>
    <participant profile_name="udp_transport_profile" is_default_profile="true">
        <rtps>
            <userTransports>
                <transport_id>UdpTransport</transport_id>
            </userTransports>
            <useBuiltinTransports>false</useBuiltinTransports>
        </rtps>
    </participant>
</profiles>

This configuration disables the shared memory (SHM) built-in transport and uses a custom UDP transport instead.

Set an environment variable to point to the fastdds.xml file by running this command in the MATLAB command window:
```
setenv("FASTRTPS_DEFAULT_PROFILES_FILE","<path-to-fastdds.xml>")
```
Note
This step is required every time you restart MATLAB.
In the MATLAB command window, run the following command to clear resources and avoid conflicts:
```
clear all;
```

Synchronize ROS 2 Distribution, Domain ID, and Middleware

If the publisher-subscriber diagnostic test fails despite a correct network adapter mode and a clean environment, verify that the following environment variables are consistent across MATLAB and the external ROS 2 system.

ROS 2 distribution compatibility — Ensure that the ROS 2 distribution running in your virtual environment outside MATLAB is supported by ROS Toolbox. ROS 2 does not generally support cross-distribution communication.
Additionally, ensure that all the system requirements align with MATLAB requirements. For a complete list of supported ROS 2 distributions, see ROS Toolbox System Requirements.
ROS middleware implementation — Ensure that both environments use the same RMW implementation. In MATLAB, open Settings from the toolstrip and select ROS Toolbox from the list of products on the left pane to verify the registered RMW implementation.
In the external environment, verify the RMW_IMPLEMENTATION variable to find the registered middleware by running the following command.
```
# For Unix, or Mac
echo $RMW_IMPLEMENTATION  # Displays middleware (blank = default FastDDS/FastRTPS)
```
If the values do not match, set the variables explicitly to ensure that the MATLAB and ROS 2 environment align with each other.
ROS domain ID — Ensure that the ROS 2 nodes created in both MATLAB and external ROS 2 environment use the same ROS_DOMAIN_ID.
To check the domain ID in MATLAB, run the following command in the command window.
```
getenv('ROS_DOMAIN_ID')
```
To check the domain ID in remote target machine, use the following command.
```
# For Unix, or Mac
echo $ROS_DOMAIN_ID       # Blank = default 0
```
Ensure that ROS_DOMAIN_ID is 0-101 or 215-232 on Linux^® and 0-166 on Windows. Follow the platform specific range mentioned in the Domain ID Platform-Specific Constraints.

After synchronizing all variables, repeat the publisher-subscriber diagnostic test. If the issue still persists, refer to Troubleshoot ROS 2 Cross-Subnet Discovery Issues Using DDS Profiles to configure DDS middleware for cross-subnet communication.