Troubleshooting

Begin with the narrowest failing boundary. Avoid changing runtime, networking, and media-server configuration at the same time.

Web UI does not load

On the RelayTV host:

cd ~/relaytv
docker compose ps
curl -v http://127.0.0.1:8787/health
docker compose logs --tail=100 relaytv

• Local failure: inspect container state and logs.
• Local success, remote failure: inspect host firewall, VLAN/routing, DNS, or reverse-proxy configuration.
• 401 or 403: verify bearer-token configuration in the client.

Web UI works but the TV is blank

The API and display runtime are different boundaries.

1. Confirm the display is connected to the RelayTV host and on the expected input.
2. Confirm the selected runtime profile matches the active host session.
3. Inspect display sockets/devices and generated Compose overrides.
4. Start a simple known-good local or direct media source.
5. Review the native runtime guide.

Playback starts and stops

Check the source from the RelayTV host, current logs, and whether the URL needs special resolution. YouTube replays that are still processing have a dedicated post-live guide.

No audio or wrong output

Confirm the host sees the intended sink, then compare automatic selection with an explicitly configured sink. HDMI audio behavior can differ between desktop sessions and direct DRM/KMS operation.

Android cannot discover RelayTV

• Keep both devices on a network where mDNS can pass.
• Check client isolation and multicast filtering on Wi-Fi.
• Add the RelayTV URL manually when discovery cannot cross a VLAN or VPN.
• Verify http://HOST:8787/health from the phone’s network.

An integration is unauthorized

Confirm whether RELAYTV_API_TOKEN is enabled, update the client profile/config entry, and make sure the token is sent as a bearer header—not in the URL.

Still blocked

Collect the minimal redacted diagnostics and open an issue. Include the host architecture, runtime profile, image version, exact reproduction steps, and the smallest relevant log excerpt.