StarMade Can't Connect to Server or Not in the Server List

When players cannot connect to a StarMade server, the cause is almost always one of three things: their client is on a different StarMade build than the server, TCP port 4242 is not reaching the server, or a setting in server.cfg (whitelist, authentication or a full MAX_CLIENTS) turns them away. If the server is missing from the list in Online Play, it also needs ANNOUNCE_SERVER_TO_SERVERLIST = true and your public address in HOST_NAME_TO_ANNOUNCE_TO_SERVER_LIST. Players can always skip the list by typing ip:port in the field at the bottom of Online Play.

Use the error the player sees to jump to the right section.

A StarMade fleet near a planet

Match the error to the cause

What happens	Most likely cause
A version error as soon as the player connects	Client and server on different builds
Connection timeout, or nothing happens for a long time	Port 4242 blocked, wrong address, or server not running
Connection refused right away	Nothing is listening on that port, usually a wrong port number
Rejected with a whitelist or ban message	`USE_WHITELIST` is on, or the name or IP is banned
Authentication failure	`REQUIRE_STARMADE_AUTHENTICATION` is on and the player has no registry login
Connects, then sits on loading or drops	Server out of memory, or a huge entity loading in the spawn sector
Server missing from the list but joinable by address	Announce settings, not a connection problem

Version mismatch

StarMade servers only accept clients on the same build. This bites most often right after an update: the launcher updates the player's client, but the server is still on the old one, or the reverse.

The fix is to get everyone on the same build:

Update the server to match. Back up server-database first, then replace the game files with the new build and start it. On a hosted server, change the server jar in the panel or upload the new files.
Or roll the player back. The StarMade launcher lets each player pick a build from its version list. Have them choose the exact version the server runs, which the server console prints on start.

Pre-release and dev builds are separate from release. If you run a release server, players on a dev build will not get in, even if the numbers look close.

Port and network problems

StarMade uses TCP on the port given by -port: in the start command, 4242 unless you changed it. Players need ip:4242 or whatever port you set.

Is the server fully up? The universe has to finish loading before it accepts players. A large server-database can take minutes on a slow disk.
Is the address right? Players type the public IP and port, with a colon, in the field at the bottom of Online Play.
Firewall. Allow TCP 4242 inbound. Windows: netsh advfirewall firewall add rule name="StarMade" dir=in action=allow protocol=TCP localport=4242. Linux with ufw: sudo ufw allow 4242/tcp.
Router. Forward TCP 4242 to the server's local IP and reserve that IP. The port forwarding guide has the general steps.
CGNAT. If your router's WAN address is not the same as the one a "what is my IP" site shows, port forwarding cannot work. See how to tell if you are behind CGNAT.
Joining from inside the same network. Use the local IP. Many routers do not loop the public IP back, so the host sees a timeout while friends outside connect fine.

If SERVER_LISTEN_IP in server.cfg is set to a specific address, make sure it is one the machine actually has. The default all is right for nearly every setup.

Server not in the Online Play list

The public list is opt in. Stop the server, open server.cfg and set:

ANNOUNCE_SERVER_TO_SERVERLIST = true //announce server to the server list
HOST_NAME_TO_ANNOUNCE_TO_SERVER_LIST = 203.0.113.10 //public IP or domain players connect to
SERVER_LIST_NAME = Frontier Factions //max 64 characters
SERVER_LIST_DESCRIPTION = PvP factions, weekly wars //max 128 characters

Then start it again. The host name must be the address the outside world reaches, not localhost or a 192.168 address, because the list hands it to players as is. The port must also be open, since the list cannot show a server it cannot reach.

Even with everything right, a list is a convenience. Put the address in your Discord or website so players can type it directly.

Whitelist, bans and full servers

Whitelist. With USE_WHITELIST = true, only names or IPs in whitelist.txt can join. Add the player, or use the admin command /whitelist_name PlayerName.
Bans. Check /list_banned_name and /list_banned_ip, then /unban_name or /unban_ip. The rest of the moderation set is in StarMade admin commands.
Full. MAX_CLIENTS defaults to 32. A player limit in server.cfg lower than your community size turns the next person away.

Authentication errors

USE_STARMADE_AUTHENTICATION lets players log in with their star-made.org registry account, and REQUIRE_STARMADE_AUTHENTICATION makes that mandatory. With the require option on, players who skipped the registry login in the launcher are refused. Either have them log in through the launcher or set it to false. Leaving it off is fine for a whitelisted friends server, but on a public server it means anyone can join under any name, so protect admin names with care.

Connects, then stuck loading or dropped

If players get past the connection step and then hang or drop, look at the server, not the network:

Out of memory. The console shows Java heap errors. Raise -Xmx in the start command, or move to a bigger plan. Big ships and many active sectors are what use it up.
Something huge at spawn. A giant station or a pile of ships in the spawn sector makes every joining player load it. Move it with admin commands, or set PROTECT_STARTING_SECTOR = true and keep spawn clear.
Corrupted entity. If one sector crashes the server every time a player enters, restore server-database from a backup taken before the problem.

Ships and stations in a StarMade sector

Skip the network checklist

Half of this page is about home networks. A GamezServers StarMade server comes with its own address and an open port, so players type it into Online Play and connect. You choose the server jar in the panel to keep the build in line with your players, edit server.cfg in the file manager, watch Java errors in the live console, and take a one click backup before an update. If you are setting one up from scratch on your own hardware instead, start with how to host a StarMade server.

FAQ

What port do StarMade players connect to?

TCP 4242 by default. If the server was started with a different -port: value, players add that port after the IP with a colon.

Why does StarMade say my version does not match the server?

Your client and the server run different builds. Pick the server's version in the launcher's build list, or ask the owner to update the server.

How long does it take to appear in the StarMade server list?

Usually soon after the server starts with announce enabled, as long as the host name and port are reachable from outside. Joining by address works the whole time.

Can friends on Mac or Linux join a Windows hosted server?

Yes. StarMade runs on all three, and the platform does not matter as long as everyone is on the same build.

My friends can join but I cannot, on the same network. Why?

Your router likely does not support loopback. Connect with the server's local IP and port instead of the public one.