Troubleshooting

Common NDI Receiver issues and how to fix them.

Source Not Discovered

NDI uses mDNS (multicast DNS) for discovery. If sources aren’t showing up:

Same network? — Sender and receiver must be on the same network subnet, or connected with a direct Ethernet cable. On a standard network, both devices should share the same subnet (e.g., 192.168.1.x). On a direct cable, both devices auto-assign link-local addresses (169.254.x.x) — wait ~30 seconds after plugging in
Firewall — mDNS uses UDP port 5353. Allow it:
```
sudo ufw allow 5353/udp
```
Network switch — Some managed switches block multicast traffic by default. Enable IGMP snooping or allow multicast on the relevant VLANs
Wi-Fi isolation — Some access points have “client isolation” enabled, preventing devices from seeing each other. Disable it or use Ethernet
NDI SDK installed? — The NDI SDK must be available on the receiver. Run ./ndi-receiver --discover to test — if it can’t find the SDK, it will tell you

The source may have stopped sending — check that the sending application is running
Try disconnecting and reconnecting from the Web UI
Check that no other application has exclusively claimed the NDI source

The receiver is running but not connected to a source. Open the Web UI at http://ndi-receiver.local:8080 to select a source
If a source is configured, it may not be available yet — the receiver will auto-reconnect when it appears

Check that the display is connected and powered on
Verify the correct DRM connector is selected: ./ndi-receiver --discover lists connectors, or check the Web UI
Try specifying the connector explicitly: ./ndi-receiver --connector "HDMI-A-1"
Make sure no desktop environment is claiming the display — NDI Receiver needs direct DRM/KMS access. Run from a TTY (not a terminal inside a desktop)

Network bandwidth: NDI 1080p needs ~125 Mbps. Use Gigabit Ethernet, not 100 Mbps
Wi-Fi: 5GHz is required for reliable NDI. 2.4GHz doesn’t have enough bandwidth
CPU load: Close other applications. Hardware video decode support is coming soon
Network congestion: Avoid running NDI alongside large file transfers or streaming

Check that the NDI source is sending audio (not all sources include audio)
Verify the correct audio device is selected — check the Web UI or set it in the config:
```
[display]
audio_device = "HDMI"
```
Audio device names are matched by substring — "HDMI" will match any output with “HDMI” in the name

Change the audio device in the Web UI, or specify it on the command line:

./ndi-receiver --audio-device "HDMI"

The .local address uses mDNS (Bonjour). If it doesn’t resolve:

macOS: mDNS works out of the box — if it’s not resolving, make sure both devices are on the same network or directly connected
Windows: Install Bonjour Print Services or use the IP address instead
Linux: Install avahi-daemon and libnss-mdns: sudo apt install avahi-daemon libnss-mdns
Direct cable: Wait ~30 seconds for link-local addresses to settle before trying the .local address

You can also find the receiver by browsing for it:

# From macOS
dns-sd -B _ndi._tcp

# From Linux
avahi-browse -rt _http._tcp

Port	Protocol	Purpose
5353	UDP	mDNS discovery
8080	TCP	Web UI (configurable)
5960-5970	TCP	NDI video streams (dynamic range)

For simplicity, you can allow NDI Receiver through your firewall entirely rather than managing individual ports.

SSH into the device and edit the config file, or use the Web UI:

ssh root@ndi-receiver.local   # password: ndi
nano /etc/ndi-receiver.toml
systemctl restart ndi-receiver

Or use the Web UI at http://ndi-receiver.local:8080.

To give your receiver a unique name (recommended when running multiple receivers):

ssh root@ndi-receiver.local   # password: ndi
hostnamectl set-hostname my-receiver
systemctl restart avahi-daemon

The receiver is now at http://my-receiver.local:8080. This persists across reboots.