An MQTT automation can look like it worked for the wrong reason. A notification might still be on screen from an earlier run, or someone might have clicked Run actions. A retained message could have arrived when a subscriber connected. None of that necessarily proves that the MQTT message you meant to test triggered the automation and led to the expected action.
Home Assistant's automation trace helps answer that specific question. It records one automation run and shows how Home Assistant evaluated the trigger, conditions, and actions. Read it alongside a deliberately harmless MQTT test. It isn't a general health score for a broker or device. This guide uses a fictional message and a persistent notification, so a failed test has no operational consequence. Work only with a broker and Home Assistant instance you administer.
The claim behind the trace test
Before opening the trace panel, write down a claim you can check. For example: “A message on lab/trace-check/event with event_type set to new_device caused this automation to create one notification.” That gives you a topic and payload value to check, along with the automation and its action.
Being specific keeps “MQTT works” from becoming a broader conclusion than the test supports. A passing run shows that one configured path worked at one time. It doesn't prove that a real device is present, that every publisher will reconnect, or that a broker will deliver future messages exactly once. MQTT quality-of-service settings describe how clients and the broker handle delivery. They don't turn one trace into a long-term reliability measurement.
If you're testing because of an unfamiliar device entry, keep the inventory question separate from the automation question. How to See Every Device on Your Network and Find Its IP Address describes how to compare router records and local observations before assigning an identity. An automation trace can't establish who owns a device.
An unmistakably fictional test message
Reserve a topic that you won't mistake for a live integration topic, such as lab/trace-check/2026-11-03/event. Use a date or short test identifier. Avoid names that might collide with a NAS, a sensor, or an alerting rule, and keep credentials, private addresses, customer names, and real household identifiers out of the example.
Use a small JSON payload that's clearly a test:
~~~json { "event_type": "new_device", "name": "Tutorial sensor", "note": "fictional trace test" } ~~~
The name and note are fictional on purpose. They don't establish that there's a new device or a security event. For an event-path check, publish the message once without the retain option. Retained state can be useful for a current value, but receiving a message after a subscriber reconnects answers a different question from receiving a newly generated event.
Record the publication time and exact topic. With one known message to match against the trace, you'll have much less to untangle.
The trigger before the action
Open the automation in Home Assistant and check that it's enabled. Then open the trace view for the run created after your test message. The trigger section should show the MQTT trigger that started the run. Compare its topic with your recorded topic, character by character. MQTT topics are case-sensitive. A suffix of /event instead of /events means a different path.
If there's no trace run at the expected time, start with the trigger. Don't change the action yet. Check the selected broker and exact topic, and confirm that you published the test after enabling the automation. Run actions executes the action sequence without MQTT trigger data and skips the automation’s top-level conditions. Conditions within the action sequence still apply. It bypasses the MQTT trigger, so it isn't evidence that the message arrived.
If a trace did begin, inspect the trigger data instead of relying on the notification text. Check that the payload is the fictional JSON you sent, with the expected value in the expected field. Malformed JSON or a missing field can prevent a template or payload match from succeeding. So can a value with different case.
Each condition in the run
Conditions explain why an automation can trigger and then stop before its action. Expand each condition in the trace and read the input Home Assistant evaluated. The editor accepting the YAML doesn't mean the condition matched.
For an MQTT trigger, a useful first test condition is deliberately narrow: event_type must be new_device. Publish a second fictional payload with event_type set to device_offline. If no new trace appears, check whether a payload filter in the trigger rejected the message. A missing trace alone does not prove this. If it shows a run that stops at the condition, you can see the separation clearly.
Neither result is a defect on its own. Check whether the behavior matches your test claim. Testing a positive case and a non-matching case can reveal missing or overly permissive payload filtering before a real message reaches an alert, a switch, or another action with consequences.
The action and its visible result
Inspect the action only after the trace shows that the trigger and conditions matched. For a first test, use a persistent notification, logbook entry, or dedicated helper. These are visible and reversible. Until you understand the basic path, avoid locks, alarms, power controls, network changes, and actions that notify people outside the test.
The action entry in the trace should show whether Home Assistant called the intended service. Compare its timestamp with the notification or helper update. If the action is there but the visible result isn't, check the action target or service data. A visible notification with no corresponding action in this run could be left over from another run.
Automation modes matter when messages arrive close together. A single automation can ignore a new trigger while a prior run is active; queued and parallel modes have different consequences. Don't change the mode just to make one test look successful. First check whether the expected test run was accepted and what the trace records.
Retained state and reconnects as separate tests
An MQTT broker can retain a message for later subscribers, and clients can reconnect after a disconnect. Either behavior can make old-looking data appear in a fresh Home Assistant session. The trace records the automation run. On its own, though, it doesn't establish when a publisher originally created a retained value.
For the first trace test, use a one-time, non-retained topic. Test retained state and availability separately later, recording the broker setting and subscriber timing. This keeps the facts separate: an automation processed a message, an entity changed availability, and a publisher created a new device event. Mixing them together makes later troubleshooting needlessly ambiguous.
An existing MQTT discovery entity isn't proof that its values are current, either. Verify the entity and its state before connecting it to an automation with consequences. The trace can then show whether the automation observed the entity or message you intended. A dashboard card that remained visible wouldn't tell you that.
A short record of the trace test
Save a brief record outside the trace with the automation name, test-only topic, fictional payload, publication time, trace run time, and action result. Keep secrets and real device data out of it. That gives someone a baseline they can repeat after an update or broker restart, instead of just a one-off check.
DeviceShelf Server can publish network observations through MQTT discovery to a Home Assistant installation you administer. An automation trace of that output is evidence about one configured message path. Compare it independently with router records and the originating service. It doesn't guarantee device identity, availability, delivery, or a future automation outcome.
Remove the test-only automation, helper, and retained test data when the check is no longer useful. The conclusion should stay narrow: at a recorded time, one fictional MQTT message caused this Home Assistant automation to reach the observed action. That's enough to locate the next issue without claiming more than the evidence supports.