ROS 2 Topics That Look Empty: Check QoS Compatibility Before Rewriting Nodes

A ROS 2 topic that appears to publish successfully may still fail to deliver the messages a subscriber expects. Quality of Service settings are part of the communication contract, and a mismatch can leave a topic empty, delayed or unreliable without an obvious application error. When troubleshooting a robot system, record the QoS settings on both sides before changing code or middleware configuration.

Record the publisher and subscriber profiles

Capture the topic name, message type, publisher node, subscriber node and the QoS policies each endpoint uses. Important fields can include reliability, durability, history, depth and deadline. Record the ROS 2 distribution and middleware implementation as well, because the same application can be deployed with different defaults.

Use the official ROS 2 Quality of Service documentation to interpret the policies and compatibility rules. A profile that works in a short laboratory test may not satisfy the timing or delivery needs of a production sensor. Keep the exact settings with the deployment record rather than describing the topic as simply reliable.

Understand compatibility as a direction

ROS 2 QoS compatibility is evaluated between what a publisher offers and what a subscription requests. Some policy combinations are compatible, while others prevent communication. Changing a subscriber from a default profile to a stricter request can therefore make an existing topic appear to disappear.

When a mismatch is suspected, compare the profiles and test a minimal compatible pair. Do not immediately lower every policy to a best-effort setting. The right choice depends on whether the data can be lost, whether late samples are useful and how the robot responds when updates stop. Document the reason for the chosen profile.

If a deployment contains multiple publishers for one topic, record each endpoint rather than checking only the first one shown by a command. Different nodes may offer different policies or message rates. A subscriber can appear to work while receiving from an unexpected source, which makes the test result misleading. Include the node names and namespaces in the communication record.

Reliability and durability answer different questions

Reliability describes how the system handles message delivery during the connection. Durability concerns what a late-joining subscriber can receive from earlier publication. A sensor stream and a configuration topic may need different choices. Treating both as a single “reliable” flag hides the decision the application actually needs.

For a control or safety-related signal, define what the robot should do when a message is late or absent. A QoS setting cannot replace an application-level timeout, watchdog or safe-stop behavior. The team should document the fallback behavior and test it under the network and CPU conditions expected in the cell.

Depth and history can change what an operator sees

History and queue depth affect how many samples are retained when the subscriber or executor falls behind. A small depth may drop older samples, while a large depth can increase memory use and latency. The useful choice depends on whether the application wants the newest state or a sequence of observations.

When diagnosing a delay, record timestamps at publication, transport and processing where the system makes those measurements available. A topic that is not empty can still be too old for a motion planner. Keep a short capture of the relevant period and identify the machine, ROS 2 version and QoS profile used.

Verify the deployed configuration

Source code defaults may differ from the profile loaded by a launch file, parameter file or composable node. Check the configuration actually deployed on the robot and record any environment variables or middleware settings that affect discovery and transport. A successful test on a developer workstation does not prove that the production network exposes the same endpoints.

The ROS 2 documentation on middleware vendors explains that ROS 2 can use different middleware implementations behind its communication APIs. That portability is useful, but it also makes it important to record the deployed implementation and test the real network rather than assuming every environment behaves identically.

Make one controlled change at a time and keep the original configuration. If the change fixes communication, record which policy was changed and what evidence supports the conclusion. If it does not, revert it before trying the next hypothesis. This makes the troubleshooting history useful to the next engineer.

Close the service record with a communication test

Define a repeatable test: start the nodes, inspect endpoint QoS, publish known messages, measure delivery and stop a dependency to verify the fallback behavior. Record the result, time window and limitations. A green command-line check is not enough if the topic must meet a latency or availability requirement under load.

For related ROS 2 concepts, see our image topic encoding guide and browse the robot software archive. A precise QoS record turns an intermittent topic problem into a testable configuration question.