An MQTT automation often starts with a reasonable idea: a device publishes an event, and Home Assistant reacts. The harder question is what that event needs to mean. Would a missed update just leave a dashboard a little untidy? Could a repeated event send two notifications? Would the action affect a lock, a heater, or another device that calls for a more conservative design?
Quality of Service, usually shortened to QoS, is part of that choice. It describes the delivery handshake requested between an MQTT client and a broker. It doesn't prove that a sensor measured correctly or that a device is reachable right now. Nor does it prove that Home Assistant completed an automation. Define the consequence first, then choose a QoS level. That gives you clearer tests than changing a number after an alert behaves oddly.
The event and its consequence
Before changing a QoS setting, write down the exact topic, payload, publisher, and consumer. A temperature report can fail in different ways than a button press or an availability signal. The next reading can replace a periodic temperature report. A button press may matter once but cause trouble if it's handled as a command twice. An availability topic may describe an application's connection to the broker rather than the state of a service on the device.
Home Assistant's MQTT integration lets entities and automations subscribe to MQTT topics. That doesn't make a message a complete health check. Check its documentation for configuration syntax and supported MQTT features. Home Assistant: MQTT If an action depends on the actual service, you still need to test that service separately.
Be precise about what you've established. “The broker accepted a publish at this QoS” is different from “the automation ran” and different again from “the physical device did what the payload described.” Keeping those distinctions clear makes an incident easier to investigate later.
Delivery behavior at QoS 0, 1, and 2
The MQTT specification defines three QoS levels for application messages. OASIS MQTT Version 5.0 These describe delivery expectations between participating MQTT clients and the broker. They aren't a ranking of data quality.
At QoS 0, the sender makes no acknowledgment-based retry request for the publication. This is commonly described as “at most once.” It can suit frequent observations that the next update can replace, such as a regularly updated measurement where a new value is more useful than an old one. Gaps can be harder to see, though. A missing message alone doesn't tell you which network or client step failed.
At QoS 1, the receiver acknowledges the publication. This is commonly described as “at least once.” With MQTT 5, unacknowledged QoS 1 publications are retransmitted when a connection resumes an existing session. The receiver may therefore receive duplicates. If an automation treats each copy as a fresh command, it may send a duplicate notification or repeat an action. Design the payload and automation so that repeating the same event is safe, or record a sequence number or timestamp controlled by the publisher.
QoS 2 uses a longer exchange intended to arrange “exactly once” delivery within the MQTT protocol flow. That isn't a general promise about what happens outside that flow. It doesn't mean the real-world event happened once or that a downstream HTTP call ran once. An automation could still be triggered again after a restart or by a different message. QoS 2 adds protocol work, so use it only after showing why the application needs that delivery behavior.
Subscription QoS
Publishing and subscribing are separate choices. When a client subscribes, it requests a maximum QoS for messages delivered on that subscription. The broker uses the applicable level for delivery. Setting a high value in one part of the path doesn't upgrade every message along it. The specification describes this negotiation; your broker's documentation or logs can show what your deployment actually accepted.
The Mosquitto command-line clients let you publish and subscribe with a selected QoS for a small, controlled check. Their options are documented in the mosquitto_pub manual and mosquitto_sub manual. Keep the test topic separate from real device commands, and never include passwords, addresses, or personal data in the test payload.
Use this sequence to keep the test reversible:
- Create a uniquely named lab topic on a broker and network you administer, such as
lab/qos-check-2026-10-21. - Start a subscriber that displays the selected QoS and note its connection time. Record its client ID, subscription QoS, clean-session/clean-start setting, and session expiry.
- Publish an unmistakable test payload with QoS 0, then repeat with QoS 1. Do not publish to a command topic.
- Disconnect only the lab subscriber at a controlled point, reconnect it, and record what arrived. Testing delivery across a disconnect requires a persistent session resumed with the same client ID; QoS alone does not preserve a subscription. Don't use this result to infer how unrelated devices behave.
- If you're testing an automation, make its first action a reversible logbook entry or persistent notification. Check the automation trace separately from the broker output.
Add QoS 2 to the same lab exercise only if you have a stated reason to compare it. A successful client connection proves only that the client can connect. It doesn't establish that a production sensor or automation has the same settings.
Duplicate messages and repeated side effects
If an automation has a side effect, plan for retries or duplicates before relying on QoS 1. An event ID in the payload gives the consumer something concrete to compare. A monotonic counter or timestamp can do the same, but use only a field that the publisher actually controls and documents. A time displayed by another system may not be comparable if clocks are wrong or formats differ.
Choose an action that's safe to repeat, or add a deliberate check before it runs. A notification, for example, can include the event ID. A command that changes a device should first compare the desired state with the current authorized observation. A short, logged cooldown may help with an alert. Make that an explicit policy decision, though, rather than a hidden way to dismiss duplicates you haven't explained.
Check retained messages separately. A client can receive a retained state message when it subscribes later; that doesn't necessarily mean an active device has just published it. Test retained state, availability, and event topics separately. Don't reuse an event topic as a retained state topic unless the publisher's design explicitly supports it.
QoS in a wider diagnosis
If a message seems to be missing, inspect the smallest relevant chain: publisher connection, broker log, topic spelling, subscription, Home Assistant configuration, and automation trace. If it appears twice, save the topic and payload along with the QoS, time, and client logs before changing settings. That record can help distinguish a publisher retry from two independent publications or two subscriptions.
An inventory or network-observation tool can give you another local clue about devices on a network you administer. DeviceShelf is one option for recording an observed address and time alongside MQTT evidence. It doesn't prove MQTT delivery, device identity, availability, or the success of an automation.
QoS is most useful when you've matched it to a documented consequence. Choose QoS 0 when it's acceptable for newer data to supersede an earlier value. Make QoS 1 consumers tolerant of duplicates. Use QoS 2 only for a demonstrated protocol need, then test the entire path that matters. You still don't have a guarantee. You do have a precise, repeatable expectation for the next event.