From 4764dcbb05e1d8e9d7a0903eeb68757c8b0f1377 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miroslav=20=C5=A0ediv=C3=BD?= Date: Fri, 31 Jul 2026 15:01:03 +0200 Subject: [PATCH] docs: add warning about using localhost for NEKO_WEBRTC_NAT1TO1 and common WebRTC connection errors. (#672) --- webpage/docs/troubleshooting.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/webpage/docs/troubleshooting.md b/webpage/docs/troubleshooting.md index 7b2574d3..baf24a12 100644 --- a/webpage/docs/troubleshooting.md +++ b/webpage/docs/troubleshooting.md @@ -159,6 +159,14 @@ Make sure that you are exposing your ports correctly. If you put a local IP as `NEKO_WEBRTC_NAT1TO1`, external clients try to connect to that IP. But it is unreachable for them because it is your local IP. You must use your public IP address with port forwarding. +:::danger Never use `127.0.0.1` as `NEKO_WEBRTC_NAT1TO1` +Setting `NEKO_WEBRTC_NAT1TO1: 127.0.0.1` tells every client to connect to *their own* localhost, not your server. The connection will time out for all clients, and the browser will report: +``` +Failed to ping without candidate pairs. Connection is not possible yet. +``` +Use your actual public IP (or leave it unset to auto-detect) instead. +::: + ## Frequently Encountered Errors {#frequently-encountered-errors} ### Getting a black screen with a cursor, but no browser for Chromium-based browsers {#black-screen-with-cursor} @@ -343,6 +351,18 @@ Check if your TCP port is exposed correctly and your reverse proxy is correctly --- +``` +Failed to ping without candidate pairs. Connection is not possible yet. +``` + +This WebRTC error means the browser received ICE candidates (IP:port pairs) from the server but could not reach any of them. Common causes: + +- **`NEKO_WEBRTC_NAT1TO1` is set to `127.0.0.1`** — never use localhost here; set it to your real public IP or leave it unset for auto-detection. +- **`NEKO_WEBRTC_NAT1TO1` is set to a private/LAN IP** — external clients cannot reach a private IP. Use your public IP with port forwarding. +- **UDP ports are blocked** — verify the ephemeral port range is exposed and reachable (see [Validate UDP ports reachability](#reachable-ports)). + +--- + ``` NotAllowedError: play() failed because the user didn't interact with the document first ```