Limits and troubleshooting

Known limits

Marine and offshore zones have no SAME code. The NWS issues those products against zone UGCs that never map to a county, so a boat or a coastal water zone produces no alert entities at all. It still gets lightning.

Non-US zones get lightning only. There is no NWS product for them. GLM coverage is the GOES-19 field of view, the Americas and the surrounding oceans, so lightning works well into Canada, Mexico and the Caribbean and not at all across the Atlantic.

Alert geometry is simplified for the wire. County unions carry roughly 550 metres of tolerance. Check geometry_source before treating a shape as precise: polygon is the forecaster-drawn storm polygon, ugc is a union of whole county outlines, none means the product shipped no geometry.

Polygons are not recorded. The geometry attribute is excluded from the recorder on purpose; see Entities and attributes. It is live in the state machine, so cards and templates see it, but it does not appear in history.

Nine counties, nine boxes. The subscription cap is covered in How it connects.

Troubleshooting

WxAlerts does not appear in the Add Integration list. Restart Home Assistant. HACS copies files into place without loading them.

Setup refuses with “no selected zone resolved to a US county”. Every zone you picked is offshore, marine, or outside the US. Turn NWS alerts off and run lightning-only.

Every entity is unavailable. The MQTT connection is down. Check that the Home Assistant host can reach mqtt.wxalerts.org on port 443 outbound, since a firewall that allows plain HTTPS but inspects and drops WebSocket upgrades is the usual culprit, then look in the log for MQTT connection lost.

No alerts ever arrive, but the entities are available. Most of the time this is just quiet weather; the connection being up means the subscription worked. To check the plumbing rather than the sky, read county_ugc off sensor.…_active_alerts and confirm it is the county you expect, then compare against a county with something live on wxalerts.org.

The lightning sensor sits at 0. No flashes landed in your box within the window. At the default 4-character box that is a 39 km square, normal on most days. Widen the box to 3 characters if you want more warning of storms approaching, and remember GLM is GOES-19 only.

An automation did not fire after a restart. Warnings already in effect when Home Assistant starts arrive as retained messages and fire no event, by design. The entities are correct; only the event bus is quiet. See Events and automations.

A _2 lightning sensor appeared alongside the original. A 0.2.0 bug tied the lightning entity’s identity to the geohash box size, so changing the box orphaned the entity. Upgrade to 0.2.1, then remove and re-add the integration.

A per-phenomenon sensor is missing. Flood, winter storm and heat are registered but disabled by default. Enable them on the entity itself, under the device.

Two zones in the same county share entities. Expected, because the county is the unit the NWS issues on. Each zone still gets its own lightning sensor.

Turning on debug logging

logger:
  default: warning
  logs:
    custom_components.wxalerts: debug

Debug logs the reconnect schedule, retained hazards that were recorded without firing an event, and any subscription trimming. Restart, reproduce, then check Settings → System → Logs.

Reporting a problem

Issues and pull requests go to github.com/wxalerts/WxAlerts-HA. A useful report has the Home Assistant version, the integration version, the debug log around the failure, and the same / county_ugc attributes of the affected entity. That last pair pins down whether the problem is the feed or the mapping from your zone to a county.