Troubleshoot connections

Read the relay’s console output and the affected game instance’s Unity console. Identify whether the failure occurs before connection, during a room join, or after the game connects. Then use the corresponding checks on this page.

The relay exits immediately

Set BLITZ_RELAY_CONNECTION_KEY in the environment that starts the relay. If HTTP is enabled, also set BLITZ_RELAY_HTTP_ADMIN_TOKEN. A variable set in a terminal is not automatically available to a separate service process.

If the error reports a port binding failure, check for another process using the port. If it reports a CORS file error, check the file path and JSON syntax. --disable-http removes the API and its admin-token requirement, but you must still set the UDP connection key.

Check --client-details and BLITZ_RELAY_CLIENT_DETAILS. Invalid values prevent startup even with HTTP disabled. Use Ids, IpAddresses, or IpEndpoints. The command-line option overrides the environment variable.

To get more log detail, restart with --log-level Debug. For all available options, see Server configuration.

HTTP works, but the game cannot connect

An HTTP health response confirms that you can reach the TCP listener. Game traffic uses UDP on a different port.

Match the transport’s Relay Address, Relay Port, and Relay Key to the running relay. Use the UDP port, which defaults to 7770, not the HTTP port, which defaults to 7771. The relay rejects a mismatched connection key before room registration.

After a package update, check the relay version. The current Netcode for GameObjects (NGO), Fish-Networking, and Mirror packages require Blitz Relay 1.3.1 or later. In Fish-Networking, check the return value of StartConnection() before starting the local host client. false means the local socket did not start. true begins the attempt; wait for the started event to confirm the connection.

In Mirror, keep the manager’s Network Address box non-empty, even though the transport uses Relay Address for the actual endpoint. Mirror rejects a blank manager address before calling the transport. WebGL builds cannot use this UDP transport.

If you run relay 1.4.0 or later, check the deployed build with the version endpoint. Unlike /health, it requires the admin token. An older relay can return 404 because the endpoint does not exist. Do not use the version endpoint as a health check for an older deployment.

For a remote relay, check the machine’s UDP firewall rules and any router or hosting-provider rules. An HTTP reverse proxy does not forward UDP game traffic. Use a direct UDP endpoint or infrastructure that supports UDP.

If the relay runs on another device, replace 127.0.0.1 with that device’s reachable address. Unless you need the socket’s DontRoute behaviour, clear the Do Not Route checkbox.

The host has no room code, or displays an old one

Before you read GetRoomCode(), wait for the transport’s server connection to reach its started state. Starting the framework or receiving NGO’s OnServerStarted event does not confirm that relay registration has finished.

The transport can retain a room code after shutdown. In NGO and Mirror, starting a new host without a pending promotion clears the previous code until registration completes. Do not treat a non-empty code as confirmation that a new session is ready. Use the connection-state checks in the session test and update your invitation UI after registration.

A connection returns a relay error

Use the error code to identify the cause:

Error	What to check
RoomNotFound	Check the eight-character room code and use the latest code from a ready host on the same relay. Malformed join frames and invalid room codes also return this error. Ephemeral rooms disappear when their host leaves; all rooms disappear after a relay restart.
RoomFull	Count relay clients against the room limit. Fish-Networking’s local host client also uses a slot. An API-created room’s limit is fixed when it is created.
InvalidMaximumClients	Request at least one client slot. For a custom transport, also check the HostRegister frame layout. The limit is an unsigned 16-bit value.
InvalidHostClaim	Complete promotion within 10 seconds using the issued claim. Setting a room code or room host token does not create a valid promotion claim.
RoomClosed	The room was closed through the HTTP API. Create or join another room.
HostRemoved	An administrator removed the persistent room’s active host. The room remains, but the former host’s session ends.

The official Unity transports stop the affected relay connection after receiving an Error frame, whether it arrives in a normal receive callback or in disconnect additional data. Check the framework’s error reporting:

• Fish-Networking logs the error name.
• NGO records a ProtocolError: a client receives OnClientDisconnectCallback with the error in NetworkManager.DisconnectReason, while a host receives OnTransportFailure with the error in the transport’s DisconnectEventMessage.
• Mirror reports client errors through NetworkManager.OnClientError and then disconnects the client. Host failures raise the transport’s custom OnTransportFailure event. Your handler must stop the Mirror host or dedicated server.

Before you reconnect, resolve the reported cause. For all error codes, see UDP protocol errors.

After HostRemoved, Fish-Networking 2.1.0 also stops the former host’s local client and clears pending promotion. The relay sends this error only to the removed host. It can still promote another client.

Players connect, but game traffic does not arrive

Check whether the room has an active host. Clients can join a persistent room while a host claim is pending. HostUnavailable means that no active host can receive game traffic. The relay drops that traffic instead of saving it for later delivery.

If the host is available, check object spawning, remote procedure call (RPC) targets, ownership, and connection state in your networking framework. The relay forwards payloads but does not configure these game features.

If you use a custom transport, send every frame on relay wire channel 0. Match game channel 0 to ReliableOrdered, 1 to Unreliable, and 2 to Sequenced. The relay ignores a data frame if its game channel and delivery method do not match. MessageCodec.IsUnreliableGameChannel() returns true for both 1 and 2; it does not select a delivery method.

Unreliable traffic drops, or a client disconnects under load

Keep ordinary and sequenced unreliable payloads within the transport’s payload limit. Neither mode supports fragmentation. NGO’s sequenced mode has a lower limit than ordinary unreliable delivery. For the limit, see NGO delivery mapping, use Fish-Networking’s GetMTU(), or check Mirror’s packet and message limits.

Sequenced delivery discards older packets that arrive after a newer packet. This is expected behaviour, not a connection failure. If the receiver needs every message, use reliable ordered delivery.

Check the relay logs for reliable queue backpressure. At a reliable queue length of 256 packets, the relay drops unreliable traffic to that recipient. Before forwarding a reliable message, it counts every packet needed, including fragments. If adding the message would take the queue above 2,048 packets, it disconnects the recipient. If one message would require more than 2,048 packets on its own, it disconnects the sender instead. Reduce message sizes or send frequency and check whether the recipient processes incoming traffic promptly. For details, see Backpressure thresholds.

A persistent room never gets a host

Connect the first player in client mode so that the relay can promote the client. Starting server mode with only a room code creates an ephemeral room instead of claiming the reserved room.

Fish-Networking changes transport roles automatically. In NGO, implement an OnHostPromotionReceived handler that waits for the relay’s disconnect, shuts down NetworkManager, waits for shutdown to finish, and starts host or server mode. In Mirror, let the relay disconnect the promoted client, wait until NetworkClient.active is false, and start host or server mode. Follow the Mirror migration guide. Complete the role change and claim within the relay’s 10-second deadline.

If the new host starts but gameplay resets, check your state-restoration code. Relay promotion restores routing, not game state. For the required game logic, see Handle host migration.

If the new host is ready but the other players cannot resume, reconnect the clients that were not promoted after host availability returns. Neither framework automatically replaces those clients’ game sessions when the relay changes host. Follow the availability-event procedure.

The HTTP API returns 401

Check the Authorization: Bearer ... header and token type. Use the server-wide admin token for room creation, room and client listings, room lookup, version lookup, and host removal. A room host token can update or close its own room and kick its clients, but it cannot call the admin-only endpoints.

After a new host claims a room, use the new token from that host’s transport. The connection key does not authorise HTTP requests, and a promotion claim token does not authorise room edits.

Preserve tokens exactly as issued, including their case. Room codes are case-insensitive. Bearer tokens and promotion claim tokens are case-sensitive.

Host removal returns 409

DELETE /rooms/{roomCode}/host removes only an active host from a persistent room. If the room is ephemeral, delete the room instead. If a persistent room has no active host, including while a claim is pending, the endpoint also returns 409 Conflict. Before you retry, inspect hasHost and hasPendingHostClaim. A 204 No Content response confirms removal, not that a replacement host is ready.