Troubleshooting

TCP works but RakNet times out

Check these in order:

1. The client has the correct Raknetify2 mod for its loader and Minecraft version.
2. The server or proxy accepting the connection has Raknetify2 installed and started without a listener error.
3. The address starts with raknet; and uses the public UDP port.
4. The hosting provider, router, and host firewall all allow UDP on that port.
5. The hostname's IPv4 and IPv6 addresses lead to the intended host and have working firewall rules.

A successful TCP connection confirms only the TCP route. Follow Firewall and router configuration to check UDP forwarding and IPv6 access. If PROXY protocol is enabled, clients must reach the listener through a configured trusted proxy.

Address already in use

Check for another process using the UDP port. Query, Geyser, and other UDP services need their own ports. Simple Voice Chat can use the shared-port integration.

You can choose another local UDP port using the direct-server listener settings or the Velocity and BungeeCord settings. Check the version requirement for the Spigot/Paper setting. Changing only a router's public port leaves the local socket conflict in place.

Joining works but transfers fail

Connect directly to the destination using its raknet; address. If that fails, fix the destination listener or network route first.

If direct connections work, check whether the destination accepts incoming transfers. A Minecraft server using server.properties needs accepts-transfers=true. Direct joins do not test this setting.

Then compare the transfer hostname and TCP port with config/raknetify2-transfers.json on the sending server. Confirm that the file was loaded after a restart and that the client supports automatic RakNet transfers. See Automatic transfers.

Encryption or protocol errors

Check the Raknetify2 versions at both ends of the connection. Update the client and the server or proxy together when a release changes the encrypted protocol. Preserve the server's authentication settings while investigating.

Mod-specific failures

Record which action triggers the failure, such as opening an inventory, receiving a resource pack, changing worlds, or spawning an entity. Compare the same action over TCP and RakNet using a separate test installation when practical.

Some custom payloads depend on the order of vanilla packets. Mod authors can declare these dependencies through the packet ordering interface.

Report a bug

Open an issue in the Raknetify2 issue tracker and include:

• Minecraft, Java, loader, and Raknetify2 versions on both ends.
• Server and proxy software versions, including any UDP forwarding proxy.
• Other installed mods and their versions.
• Steps to reproduce the problem and what you expected to happen.
• Whether the same steps work over TCP.
• Relevant client, server, and proxy log excerpts from the same attempt.

Remove access tokens, passwords, and other private information before uploading logs. Preserve the exception messages and stack traces needed to diagnose the problem.