Three ways Home Assistant MQTT discovery fails quietly

Linux companion agent publishes all of a machine’s state as one retained JSON document and gives each entity a template that picks out its value. These were the cases where that produced an entity stuck at Unknown with no error anywhere.

The JSON-schema light ignores value_template. Home Assistant’s MQTT light has several schemas. The JSON one expects its own payload shape on its own topic and does not apply a template, so a light pointed at the shared document never updates. The default schema does honour templates.

A hyphen in a key breaks dot notation. value_json.cpu-temp is parsed by Jinja as a subtraction. Templates have to use value_json['cpu-temp'].

A service’s PATH is not your shell’s. A backend decided whether it applied by looking for its command, zpool, on the PATH. Under systemd the PATH is minimal, the lookup failed, and the backend never registered. The entities did not go missing with an error; they were never announced.