Troubleshooting networking

1. Mac-local firewall denying inbound

The most common cause, and the hardest to spot — because the firewall doesn't warn you; it just silently drops the connection. If the source (NAS, Proxmox, HA) shows the webhook as sent successfully but Tempo never receives it, start here.

Diagnose: from the source, check that port 7776 on the Mac is actually reachable.

curl -v http://your-mac.local:7776/health

A 200 OK means you're in the clear — skip to scenario 2 or later. A timeout or "No route to host" means something is blocking the connection before it reaches Tempo.

Fix: check three things on the Mac, in order:

• Apple Application Firewall — System Settings → Network → Firewall. If enabled, either turn it off for testing or add Tempo to the allow list (Options → "+" → Tempo.app → Allow incoming connections).
• Little Snitch — outbound rules are the default surface, but Little Snitch also enforces inbound rules separately, and the default is deny. Open Little Snitch → Rules → filter by "Incoming Connections" → add an allow rule for Tempo on port 7776.
• LuLu — same idea: it will silently drop inbound unless Tempo is allowed. Check the rule list for Tempo and add one if missing.

Tempo's diagnostic bundle (Settings → Help → Export diagnostics) includes a firewall.txt that reports ALF state and detects Little Snitch / LuLu / Murus / Radio Silence / Hands Off. Attach it when asking for help.

2. Source is on a different VLAN

Homelab networks usually segment trusted Macs from IoT, cameras, and servers. If your Mac is on VLAN 10 and Home Assistant is on VLAN 40, the firewall rule on your router is almost certainly default-deny between them.

Diagnose: from the source, try to reach the Mac by IP (not hostname, to rule out DNS):

ping 192.168.10.20
curl -v http://192.168.10.20:7776/health

If ping times out but the Mac is clearly up, the router is dropping the packets between VLANs.

Fix: add a rule in your router's firewall allowing the source VLAN to reach the Mac's IP on TCP port 7776. On UniFi: Settings → Firewall & Security → Firewall Rules → Create New Rule, action Allow, source IP/VLAN of the webhook emitter, destination IP of the Mac, destination port 7776. On pfSense: Firewall → Rules → [source VLAN tab] → Add with the same parameters.

Keep the rule narrow — specific source IP, specific destination IP, specific port. Tempo's ingestion is token-authenticated, so the firewall isn't your only defense, but a tight rule is good hygiene.

3. Hostname doesn't resolve from the source

your-mac.local relies on mDNS, which typically doesn't propagate across VLANs or through some routers' split-horizon DNS. Your Synology or Proxmox may resolve your-mac.local locally to something wrong — or not at all.

Diagnose: from the source, check what hostname actually resolves to:

dig +short your-mac.local
getent hosts your-mac.local
# or, universally:
host your-mac.local

If nothing returns, or the IP returned is wrong, the source can't use the hostname.

Fix: use the Mac's LAN IP in the webhook URL instead of its hostname. Pair it with a DHCP reservation in your router so the Mac always gets the same IP — then the URL stays stable.

If your router supports mDNS Reflector / Bonjour Relay (UniFi does, most prosumer routers do), you can enable it to make .local work across VLANs. That's a convenience — the IP-based URL is the robust answer.

4. AP / client isolation on the network

Guest WiFi networks and "IoT-safe" WiFi modes often enable client isolation, which prevents devices on the same network from talking to each other. The webhook emitter can reach the internet but not your Mac — even though they're on the same SSID.

Diagnose: try scenario 2's ping and curl from the source. If both fail and the source and Mac are on the same subnet (same VLAN, same SSID), isolation is the suspect.

Fix: disable client isolation on the WiFi network where the source lives, or move the source to a network where it's off. On UniFi: WiFi → [network] → Advanced → Isolate Client Devices, turn off. On most consumer routers, look for "AP Isolation" or "Guest Network Isolation" in the wireless settings.

The right answer here is usually not to disable isolation network-wide but to use a dedicated "trusted device" VLAN/SSID for things that need to talk to each other (Mac, NAS, HA, monitoring). Add a firewall rule as in scenario 2 if they must cross VLANs.

5. Double NAT or a CGNAT router in the path

Less common on a single-LAN homelab, but real when your ISP router has been chained behind a second router (typical with UniFi Dream Machines, Firewalla, or when the modem is in router mode). The source sees a NAT'd address of your Mac, not the Mac itself — and the reply path breaks.

Diagnose: from the Mac, check what inbound packets actually arrive on port 7776 when you trigger the webhook.

sudo tcpdump -i any -A 'tcp port 7776'

If you see nothing at all, the packets aren't crossing the NAT boundary. If you see SYNs but no complete handshake, a firewall is blocking the reply direction (unlikely on a well-configured home router — more likely scenario 1 or 2).

Fix: either bridge the upstream router so you have a single NAT, or add an explicit port-forward on the upstream device pointing port 7776 at the Mac's IP on the inner network. The cleaner fix is always to eliminate the double NAT.

If you needed a port-forward to make this work, reconsider exposing Tempo to the broader network. Tempo's ingestion is designed to run on a trusted LAN segment; crossing into territory where you're punching holes in firewalls usually means the architecture is off, not the firewall.