ROS 2 QoS Policies and DDS Endpoint Compatibility
Two ROS 2 nodes can discover the same topic and still exchange no messages. A frequent cause is a mismatch between the Quality of Service (QoS) settings offered by a publisher and those requested by a subscriber. This guide explains ROS 2 QoS policies, how DDS endpoint compatibility works, and how to choose profiles for sensor streams and command-oriented data without treating middleware settings as a substitute for application-level safety.
What Are ROS 2 QoS Policies?
Quality of Service is a set of policies that describes how a communication endpoint handles data: how many samples it keeps, whether delivery can be retried, whether late subscribers can receive retained samples, and which timing or liveliness expectations apply. A QoS profile combines these policies for a publisher, subscription, service, or client.
ROS 2 exposes these settings through its client libraries and middleware interface (RMW). Common ROS 2 middleware implementations use DDS, whose Data Distribution Service specification defines a data-centric publish-subscribe model with delivery behavior and QoS. ROS developers usually configure QoS through ROS APIs rather than DDS directly. The ROS project provides the broader libraries and tools; the ROS 2 QoS documentation describes ROS policies, profiles, and endpoint matching.
QoS is not a single “high quality” switch. Each policy expresses a different constraint or trade-off, and the settings need to fit the data and the other endpoint. A profile that is suitable for a lossy camera stream may be unsuitable for a state update that must reach a controller.
Why QoS Exists
Robot software runs across very different communication conditions. A sensor may publish at a high rate over a wireless link where occasional samples are less important than low latency. A subscriber may start after a publisher and need the latest configuration or map metadata. A monitoring node may need to know that expected updates have stopped.
One transport behavior cannot serve all of these situations. ROS 2 QoS lets applications express policies so middleware can select compatible endpoints and manage data accordingly. This flexibility also introduces an important operational difference from systems where matching topic names and message types are enough: ROS 2 endpoints can discover one another but fail to connect when an offered policy does not satisfy a requested policy.
How QoS Works: Policies and Endpoint Matching
A publisher offers what it can provide. A subscription requests the minimum behavior it is willing to accept. For policies that participate in compatibility, a connection is possible only when the offered settings meet the request. The rule is evaluated across the relevant policies; one incompatible setting is enough to prevent communication.
| Policy | What it controls | Compatibility or operational effect |
|---|---|---|
| History and depth | Whether middleware keeps the last N samples or attempts to keep all samples; depth sets N for KEEP_LAST |
Primarily governs each endpoint’s local history and resource use, not the offered/requested match |
| Reliability | RELIABLE delivery behavior or BEST_EFFORT delivery behavior |
A reliable offer can satisfy either request; best effort cannot satisfy a reliable request |
| Durability | Whether data is only for current readers (VOLATILE) or retained by the publisher for late joiners (TRANSIENT_LOCAL) |
A transient-local offer can satisfy a volatile request; a volatile offer cannot satisfy a transient-local request |
| Deadline | Expected maximum interval between samples | The offered interval must be no greater than the subscription’s requested interval |
| Liveliness | How the middleware determines that a publisher is still active | An offered liveliness kind must be at least as strong as the requested kind |
| Lease duration | How long liveliness can go unasserted before the publisher is considered not alive | An offered lease must satisfy the subscriber’s requested lease duration |
| Lifespan | How long a sample remains useful after publication | Expired samples are discarded; choose a duration based on application freshness needs |
This table summarizes ROS-level behavior; exact defaults, supported policies, and middleware mappings depend on the ROS distribution and selected RMW implementation. For a profile that specifies SYSTEM_DEFAULT, consult that implementation’s documentation rather than assuming every machine chooses identical values.
The offered/requested rules that commonly break connections
Reliability and durability are common causes of a topic that appears but delivers no data:
| Publisher offers | Subscription requests | Compatible? | Meaning |
|---|---|---|---|
BEST_EFFORT |
RELIABLE |
No | The publisher does not promise the delivery behavior requested by the subscriber |
RELIABLE |
BEST_EFFORT |
Yes | The subscriber accepts the publisher’s stronger delivery behavior |
VOLATILE |
TRANSIENT_LOCAL |
No | The publisher does not retain data for a late-joining subscriber |
TRANSIENT_LOCAL |
VOLATILE |
Yes | The subscriber can receive new data without asking for retained history |
| Faster offered deadline | Slower requested deadline | Yes | The publisher can meet the subscriber’s maximum interval |
| Weaker offered liveliness | Stronger requested liveliness | No | The publisher cannot meet the subscriber’s liveness expectation |
Deadline and liveliness also affect compatibility. For example, a subscriber that requests updates every 50 milliseconds cannot be satisfied by a publisher offering a 100 millisecond deadline. A manual-by-topic liveliness request cannot be met by an automatic liveliness offer. The exact policy comparisons are documented in the ROS QoS guide; a connection must satisfy every applicable policy, not just reliability.
History and depth need a different kind of attention. A small KEEP_LAST queue can discard older samples when a consumer falls behind, while a large queue consumes more memory and can leave stale data waiting to be processed. These choices do not repair an incompatible reliability or durability pair. Lifespan can discard old samples after a time limit, but does not make callback execution timely.
Components and Common Profiles
ROS 2 provides predefined profiles for common patterns, but applications can construct their own. The default publisher/subscription profile commonly uses KEEP_LAST with depth 10, reliable reliability, and volatile durability. The sensor-data profile instead prioritizes fresh readings and uses best-effort reliability with a smaller history. Confirm the profile and defaults in the installed distribution and RMW implementation before depending on them.
For a high-rate range sensor, a subscriber may choose best effort so a slow or lossy connection does not prioritize retransmitting old readings over receiving newer ones. A subscriber requesting reliable delivery would not match a best-effort sensor publisher. Conversely, commands that must be received should not simply copy a sensor profile: reliability, freshness, acknowledgments, timeouts, and safe behavior after communication loss must be designed for the application.
TRANSIENT_LOCAL durability is useful when a late-joining subscriber needs recent retained samples, such as a publisher’s current state. Retention is associated with the publisher: it is not a durable database that survives the publisher’s shutdown. DEADLINE can express an expected update interval, and LIVELINESS can expose that a publisher has stopped asserting that it is active. Neither policy schedules callbacks nor proves that the underlying physical sensor is healthy.
Real-World Use Cases
- Cameras and range sensors: High-rate readings often favor low latency and bounded queues. If a frame is already stale, retransmitting it may be less useful than accepting a later frame.
- Robot state and configuration: A late-starting observer may need a recent state sample, making transient-local durability relevant when the publisher remains available.
- Control and command paths: Reliable delivery may be appropriate, but endpoints also need explicit command validity windows, watchdogs, and safe responses to timeouts. Middleware acknowledgment is not proof that a motor executed a command.
- Health monitoring: Deadline and liveliness policies can help detect missing updates or inactive publishers. Applications must still decide how to report and respond to those events.
- Recording and visualization: Tools may use different QoS from a production node. A recorder or viewer that requests incompatible QoS may fail to receive an otherwise active topic.
For the full ROS graph and middleware context, see the ROS 2 architecture explainer. Applications connecting constrained microcontrollers to a host can also use the micro-ROS client and Agent architecture. QoS is one part of a larger sensor pipeline; the robotics sensor integration guide covers timestamps, frames, calibration, and downstream estimation.
Practical Guide: Inspect and Configure QoS
Start from the data’s needs. Decide whether losing a sample is acceptable, whether a late subscriber needs previous data, how much history is useful, and what update interval is meaningful. Then inspect both endpoints rather than changing a profile at random.
In a sourced ROS 2 environment, list topics and inspect a topic’s endpoint details:
source /opt/ros/$ROS_DISTRO/setup.bash
ros2 topic list --show-types
ros2 topic info /scan --verbose
The verbose output shows discovered publishers and subscriptions, including their QoS settings. Compare the offered publisher settings with each subscriber’s requested settings. If discovery is absent altogether, check network and domain configuration as well; QoS cannot connect participants that cannot discover each other.
An rclpy subscriber can set a sensor-oriented profile explicitly. Add these imports and create the subscription inside a node class that already has a scan_callback:
from rclpy.qos import (
DurabilityPolicy,
HistoryPolicy,
QoSProfile,
ReliabilityPolicy,
)
from sensor_msgs.msg import LaserScan
sensor_qos = QoSProfile(
history=HistoryPolicy.KEEP_LAST,
depth=5,
reliability=ReliabilityPolicy.BEST_EFFORT,
durability=DurabilityPolicy.VOLATILE,
)
self.subscription = self.create_subscription(
LaserScan,
'/scan',
self.scan_callback,
sensor_qos,
)
This profile is only suitable if the publisher offers compatible QoS and the application can tolerate dropped samples. It will not connect to a publisher that offers only volatile data when the subscriber requests transient-local data, nor will it satisfy a reliable request from the publisher side when the publisher offers best effort. A command topic or safety-related state needs a separate profile selected from its failure requirements.
When diagnosing a mismatch:
- Confirm that the topic name and message type are identical on both endpoints.
- Use
ros2 topic info /topic_name --verboseto identify each endpoint and its QoS. - Check reliability, durability, deadline, liveliness, and lease duration first; compare the offer against the request.
- Review history depth and lifespan for dropped, stale, or delayed samples after compatibility is established.
- Check RMW implementation, ROS domain, network discovery, and middleware configuration if endpoints are not visible or behavior differs across machines.
Common Misconceptions
“If the topic is listed, the endpoints are communicating.” Topic discovery and endpoint matching are separate. A subscriber can see the topic name while an incompatible QoS policy prevents a connection.
“Reliable means the application cannot lose a command.” Reliable QoS requests middleware delivery behavior, but it does not confirm that a callback ran, a controller accepted a command, or hardware completed an action. Applications need acknowledgments and safe timeout behavior where those guarantees matter.
“A deeper queue always improves reliability.” More history can absorb a short processing delay, but it also consumes memory and can preserve readings that are no longer useful. For some sensors, processing the newest sample is preferable to catching up on old ones.
Related Articles
- ROS 2 architecture, DDS, and communication patterns
- micro-ROS for embedded robots
- Robotics sensor integration and data pipelines
Changelog
- Initial publication.

