Can't connect to your Project Zomboid server
Find where the connection fails, then check the matching cause. If you have not joined before, start with the connection guide.
- Check who is affected
- Read the server console
- Match the error to a cause
- Send useful details to support if needed
Can one player not join, or can nobody join?
Section titled “Can one player not join, or can nobody join?”Ask another player to try the same server address. If nobody can join, check startup, the assigned address and the server build first. If one player cannot join, compare that player’s saved Favorites entry, client build, account details and mods with a player who can. Do not reset the world to test a connection problem.
The server is offline or still loading
Section titled “The server is offline or still loading”Open Console in the game panel. If the server is Offline, start it. If it is Starting, wait for the log to settle and check the first relevant error. The SERVER STARTED line marks when the panel sees the server as started; it does not prove the world and mods loaded without errors. Check later console lines and try a join.
If startup stops on a save or mod error, keep the error text. For a save error, see Getting server information stays stuck; for mods, see the mod guide.
Server failed to respond: check the IP and port
Section titled “Server failed to respond: check the IP and port”Open Network in the panel. Each OXY Project Zomboid server has two allocations shown as IP:port. Use the primary allocation as the game address in Join → Favorites: put its IP in IP and its port in Server port. Edit an old Favorites entry if its address changed. Follow the connection guide for the other fields.
The second allocation is the UDP/Steam port. With Steam / UDP Port set to auto, it is the game port plus one. Both allocations are needed for the server; players join using the primary game port. The startup log also shows [oxy] game port X / udp port Y. Use the allocations assigned to your server rather than a port number from another guide. Ask support if an application needs an additional port.
Your game build does not match the server
Section titled “Your game build does not match the server”Compare the exact client version with the version in the server startup log. In Startup, Steam Branch left empty selects Build 42; legacy41 selects Build 41. Changing the server branch requires a reinstall. Do not reinstall just to test a join: Build 41 saves are not compatible with Build 42. If you are unsure which world or build you need to keep, ask support before changing the branch. The connection guide shows how a Steam player selects legacy41 on the client.
Wrong password or account name
Section titled “Wrong password or account name”Account username and Account password belong to that player’s character on this server. They are different from the shared Server password, which the owner may set in .cache/Server/<ServerName>.ini as Password=. The default Server Name is Pterodactyl; check the active name before opening the file. The admin account credentials are under Startup → Admin Username / Admin Password. Do not enter your panel or Steam password as the game account password. Keep the same account name spelling when returning to an existing character.
A mod is missing or does not match
Section titled “A mod is missing or does not match”If the game asks for Workshop items, let the download finish and reconnect. If a mod fails to load or the server reports a mod error, compare the active server mod list and each mod’s supported build. The owner can use the PZ Mods guide to check Workshop items, dependencies and the server profile. Keep the first console error; do not delete the save or mod files as a first step.
Getting server information stays stuck
Section titled “Getting server information stays stuck”This message does not prove a network or port problem. Check the Console for save, database and mod errors around the time of the failed join. In previous OXY cases, a corrupt save caused this symptom. If the console points to save corruption, preserve the current files and inspect a suitable backup with the world restore guide before replacing anything. If the console does not identify a cause, send the log excerpt to support.
Direct Connect works, but the Internet browser does not show the server
Section titled “Direct Connect works, but the Internet browser does not show the server”Try the primary IP:port from Network in Favorites. If that works, the server is reachable by address; a missing Internet listing alone does not show that joining is broken. Share the direct address with players and send support the server address and time if you need help with its browser listing.
You use a non-Steam or GOG copy
Section titled “You use a non-Steam or GOG copy”OXY Project Zomboid servers use Steam mode by default. There is no non-Steam/GOG switch in Startup. Contact support with your client edition so they can check what is possible for your server; a non-Steam connection is not guaranteed.
Stop or Start stays stuck
Section titled “Stop or Start stays stuck”Watch the Console and wait until its output is quiet. If Stop still hangs, use Kill at the top right of the panel, then Start and read the console. Kill ends the process without a clean save, so use it only after waiting for normal shutdown. If it hangs again or the console reports a save error, create a support ticket with the time and relevant console lines. See Start, stop and restart for the power controls.
Extra tips
Section titled “Extra tips”- Check the first error: later log messages may be consequences of an earlier save or mod failure.
- Keep the working address: a successful direct join is useful evidence when the browser listing is missing.
- Protect progress: back up the world before changing a branch or replacing save files.