An MQTT publisher can connect to a broker and still leave a Home Assistant automation silent. Often, the network isn't the problem. The publisher sent to one topic while the subscriber listened to another, or a payload filter rejected a message that looked right at first glance.
This guide assumes you administer the broker, Home Assistant instance, and test topic. It walks through a small test to isolate a topic mismatch before you change a real sensor, a NAS, or an automation whose actions have consequences. A successful test tells you what happened on that path. It doesn't prove that a device is healthy, that a network is secure, or that another automation will behave the same way.
The exact path before any edits
Start by writing down four literal values: the broker, the topic the source publishes to, the topic configured in Home Assistant, and the payload the automation expects. Copy the topic strings. Don't rely on memory. MQTT topic names are case-sensitive, and a misplaced slash, space, or topic level means a different destination.
Give each topic a narrowly defined meaning. lab/nas/availability and lab/nas/status might sound interchangeable, but they're different topics. A topic that reports a service state shouldn't quietly become a command topic, either. Keeping events, states, and commands separate lets you test one meaning at a time.
The OASIS MQTT Version 5.0 specification defines topics and subscriptions as protocol concepts, but it doesn't give topic names universal meanings. Those come from the publisher and subscriber configuration in your installation.
Home Assistant's actual subscription
Home Assistant's MQTT integration lets you listen to a topic while testing your setup. Home Assistant: MQTT Start with the exact topic. A temporary wildcard can help you find a message during a controlled lab test, but use it for diagnosis. It isn't a reason to leave an automation subscribed broadly.
Record the topic, payload, and time of the message you receive. If the expected test message doesn't appear, compare the recorded publisher topic with the configured listener topic, character by character. Then check the broker address and port. Changing connection settings won't fix a difference between two topic strings.
If the listener receives the message but the automation stays quiet, check the trigger configuration next. Home Assistant documents MQTT triggers separately from the integration itself. Home Assistant: MQTT trigger The topic can match while a payload or template condition excludes the message. Delivery to the listener is confirmed, but that doesn't establish why the automation produced no result. Check the automation's enabled state, trigger, conditions, execution mode, and trace.
A dedicated test topic and harmless payload
Don't test by publishing to a topic that operates equipment. Create a short-lived topic with a name that clearly marks it as a lab value, such as lab/mqtt-topic-check-2026-10-22. Use a payload such as test-arrived. Don't use a password, inventory, address, or realistic command. If several people administer the broker, document the topic before using it.
Set up a temporary MQTT trigger for that exact test topic. Make its first action reversible: a persistent notification, a logbook entry, or an update to a dedicated test helper. Home Assistant conditions control whether an automation continues after a trigger. Home Assistant: automation conditions Keep the condition simple enough that you can explain it from the captured payload.
This sequence is enough to separate common mistakes:
- Listen for the exact lab topic in Home Assistant and note the start time.
- Publish one clearly marked test payload from a client you control.
- Check whether the listener received the same topic and payload.
- Check whether the message published in step 2 triggered the temporary automation, using its trace and harmless action.
- Publish a deliberately different payload that the condition should reject, then confirm that no action occurred.
- Remove or disable the temporary automation and stop using the lab topic when the check is complete.
This doesn't test all retained messages, broker restarts, or delivery guarantees. Those need separate checks. It tells you only whether the named topic and rule match the message you deliberately sent.
Topic mismatches and payload mismatches
If the listener receives nothing, look first at the publishing topic, broker connection, or subscription. If it receives the expected message but the automation stays inactive, the more likely causes are the automation's trigger, payload condition, mode, or disabled state. Keep that distinction in your notes. Don't change every setting at once.
Compare payloads as carefully as topics. A filter expecting online doesn't match Online. Comparing the entire payload as text differs from extracting and comparing a field from parsed JSON, and even a hidden newline can matter in a simple comparison. Don't widen a filter just to make the test fire. Capture a non-sensitive test payload, write down the expected format, and adjust only the part that differs.
Retained messages can confuse the picture, too. After connecting, a subscriber can receive the broker's retained value even though the source hasn't published a fresh event at that moment. Home Assistant documents the behavior of availability settings separately. Home Assistant: MQTT availability A retained state can be useful as last-known information. It doesn't establish that a NAS, sensor, or service is currently available.
Careful application to the real automation
Once you understand the lab path, compare it with the real automation one field at a time: topic, payload expectation, condition, and action. Don't copy a wildcard or test-only payload into a production rule. If an action changes power, security, backups, or network configuration, start with a notification or log entry. Review the result before allowing the action with consequences to run.
Keep a short record of the evidence: the test topic, payload format, time, what the listener received, and what the automation did. A later administrator can use that record to tell an actual message-format change apart from a broker outage or a disabled rule. It also helps prevent a lack of evidence from becoming a claim that a device has failed.
DeviceShelf Server can publish network observations through MQTT for a network you administer. Those observations can be one input to compare with broker and automation records. They don't prove that a topic was delivered, that a device is identified with certainty, or that an automation completed. Check each observation independently.
The result is limited, but you can test it: one deliberately sent message matched one intentionally configured topic and caused one reversible action. That gives you a sound starting point for diagnosing the next mismatch before touching a real device.