Troubleshooting

Troubleshooting

Real error messages encountered running Portal with NetherNet, what they actually mean, and how to fix them. If you hit something not on this list, check NetherNet Transport and Backend Transports for the background first.

Player connection issues

start ICE: context deadline exceeded (signaling succeeded, then this)

You'll see this after nethernet: GET /v1/join and POST /v1/join/... already logged successfully — meaning the client found the proxy fine, but the WebRTC media channel (UDP) couldn't establish.

• Works from the same machine, fails from a phone/another device on the network: almost always a firewall blocking inbound UDP on network.nethernet.udp_ports (default 19133). See NetherNet Transport's firewall section for the exact New-NetFirewallRule command.
• Still fails after opening the firewall port, or players are on a different network entirely: configure network.nethernet.ice_servers with at least a STUN server. See NetherNet Transport.
• One isolated failure followed by an automatic successful retry a few seconds later, with no repeat afterward, has also been observed on a cold start — not fully explained, but self-recovers and hasn't recurred once a connection is established. Worth keeping an eye on if it happens repeatedly rather than once.

A specific player can't connect via NetherNet but everyone else can

Rule out an outdated Bedrock client before assuming a server problem — the client-side logic to try NetherNet before falling back to RakNet requires a client version that supports it. See NetherNet Transport's caveat section.

TOFU / "trust this server" prompt reappearing for returning players

Expected — Portal's NetherNet identity key is regenerated every restart by default. See NetherNet Transport's server identity section. There's currently no way to persist it across restarts.

Backend server registration issues

bind: Only one usage of each socket address ... is normally permitted (on the backend server, mentioning a udp_ports value)

Two NetherNet listeners on the same machine are trying to use the same UDP port — almost always Portal's own network.nethernet.udp_ports colliding with a backend server's own NetherNet UDPPorts (Dragonfly) when both run on localhost/the same host. Give each one a distinct value. See Backend Transports's udp_ports collision section.

no listeners could be created; the server is unreachable (Dragonfly)

Follows directly from the port-bind failure above (or any other listener failure): if a Dragonfly server's only configured transport fails to bind, it ends up with zero working listeners and is completely unreachable, even though the process keeps running. Fix the underlying bind failure, and consider listing Transport = ["raknet", "nethernet"] instead of NetherNet alone, so a NetherNet-specific failure doesn't take the whole server offline.

nethernet address must be the full URL of the server's signaling endpoint ..., got "host:port" (Portal rejects RegisterServer)

The backend registered with Transport: "nethernet" but a plain "host:port" Address — leftover from raknet. Fix the client library's config to use the full URL form, e.g. "http://host:port". See Backend Transports's address format table.

build request: parse "host:port/v1/join": first path segment in URL cannot contain colon (health check failing on a registered server)

Same root cause as above, just surfacing from the health checker instead of registration — the server's registered Address isn't a valid URL for its declared nethernet transport. If you're running Portal from before the registration-time validation existed, this is what you'd see instead of an immediate rejection; upgrading Portal turns this into a clear error at registration time.

ServerAddress is invalid: http://host:port (on the Dragonfly backend's own log, during a transfer)

This is the opposite mistake from the one above, in the other config: Dragonfly's own config.toml, under [Network.NetherNet], has Address set to a full URL ("http://...") instead of a bare "host:port" (or empty string). Network.NetherNet.Address is a raw TCP bind address for Dragonfly's own listener, not a URL — only the value your client library sends as RegisterServer.Address should have the http:// prefix. See Backend Transports's address format section, and your client library's own docs (e.g. PortalDF's Wiki for Dragonfly) for a worked example with both side by side.

A client library reports an invalid-configuration error before even attempting to connect

Some client libraries (check that library's own docs for which) validate their own Transport/address config locally before ever contacting Portal, specifically so this class of mistake surfaces immediately in your own server's log instead of a confusing failure deep inside Portal later. Fix the two fields to match, per Backend Transports.

unsupported protocol version right after upgrading

The socket protocol version was bumped to 3 to add RegisterServer.Transport — Portal and every backend library must be upgraded together. See Socket Protocol's protocol version note.

Transfer issues

unexpected packet (ID=5) logged by the old server right as a transfer completes

This is IDDisconnect — Portal sends a Disconnect packet to the server a player is being transferred away from, as an optimization originally aimed at GeyserMC→Spigot setups so they clean up the stale session immediately instead of waiting out a RakNet timeout. Some backend implementations (Dragonfly included) log receiving this as an error-level "unexpected packet," but it doesn't actually break the transfer — check that the transfer itself is reported as completed successfully in Portal's own log; if it is, this line is just noisy, not a failure.

PacketViolationWarning ... invalid enum value ... packetId: 63 disconnecting the player mid-transfer

Packet 63 is PlayerList. This was a real bug (a make([]T, n) + append double-length slice, sending the client a batch of garbage entries) fixed in Portal — if you're seeing this, make sure you're on a build that includes the clearPlayerList fix (any build after the NetherNet backend-transport work landed). Not related to which transport is in use; it could in principle have affected RakNet-only setups too, just less visibly, since RakNet tends to tolerate a single malformed packet better than NetherNet's stricter SCTP framing does.

Still stuck?

Turn logger.level up to debug in Configuration if it isn't already — most of the messages above only appear at that level — and check both Portal's log and the specific backend server's own log side by side; the two together usually pinpoint which of the two config files (see Backend Transports) is actually wrong.