Troubleshooting

Start with the Log

Every server writes to logs/ beside itself, and to the console. Almost every question below is answered in the first twenty lines of a start-up log, which report the port it bound, the database it opened and how much content data it loaded.

If you are going to ask for help, have that. “It does not work” and the first twenty lines of the log are very different questions.

The Server Exits Immediately

Something else is on the port. The log says so. Either stop the other thing or change SERVICE_PORT. On Windows this is often a previous copy of the same server that did not exit.

It cannot write where it is. If you extracted into Program Files or another protected directory, the database and log files fail to open. Move the whole directory somewhere you own.

The Server Starts but Reports Zero Monsters

The content data did not import. The server keeps running because an empty world is still a world, but nothing will spawn.

On a first run this usually means the archive was extracted incompletely, or extracted with a tool that skipped the large data file. Re-extract the whole archive.

If you switched to MySQL, check that the content database name in settings.cfg matches the one the schema created. A mismatch is not an error: the server opens a database that exists and is empty, and there is nothing for it to complain about.

Players Cannot Connect from Outside

Work through these in order, because each one makes the next testable.

1. From the server machine itself. If the client cannot connect to 127.0.0.1, nothing else matters and the problem is the server or the client version.
2. From another machine on the same network, using the server’s local address. Failing here means the machine’s firewall. Check the protocol as well as the port: the games here are not all on the same one, and a rule for the wrong protocol looks exactly like a rule that is not there. Configuration says which your game uses.
3. From outside, using your public address. Failing only here means port forwarding.

Test from a phone on mobile data rather than from your own network. A router that reflects traffic back to itself will make step three appear to pass when it has not.

The Client Connects and Then Drops

Almost always a version mismatch: a client for one version of the game talking to a server for another. The server logs the version it expects. Neighbouring versions are the ones that catch people out, because their clients look alike and are not interchangeable.

The second cause is stale client files. If you have patched your client/ directory, a player running the old files may get far enough to connect and then fail on the first message that changed shape.

The Launcher Says the Server Is Offline

The launcher asks the server directly, so this is a real answer rather than a guess. Either the server is not running, or the launcher is pointed somewhere else.

Check launcher.ini beside the launcher: it holds the address and it is the file to edit if you changed the port. A launcher that says offline against a server you can see running is nearly always pointed at the wrong host.

The GameCP Shows the Game Offline While the Game Is Up

The GameCP reads a status channel on the loopback address of the machine it is running on. If the panel and the game server are on different machines, it cannot reach it, and reporting offline is the correct answer to the question it can actually ask.

Run both on the same machine, which is what the archive assumes.

The Console Did Not Print a Bootstrap Password

On a fresh server the GameCP prints a one-time password on start, which is how you make the first staff account without a database tool. It is printed as a warning across several lines, so it is easy to scroll past. Search the log for NOBODY IS AN ADMINISTRATOR to find the block, and the password is the line below it that begins Password:.

The file is the more reliable place to read it back: the same value is written into settings.cfg under [webserver], on the SUPER_PASSWORD line, and it stays there until it is used. If that line is blank and no block appeared in the log, it is one of two things.

Somebody already holds Super Administrator on this game. The door only opens while nobody is behind it, and the panel closes it again on every start, blanking the value in settings.cfg and logging that it did. That is the expected state on a server you have already set up, and on a second start after you promoted yourself. Check who holds one with gmadmin list --game <key>, from the tools folder of the download. If it is your own account, sign in and use the control panel. If it belongs to somebody you cannot reach, revoke it with gmadmin revoke <email> <key> and restart the panel, and a fresh password is printed.

The file cannot be written. The password is written into settings.cfg before it is printed, so a settings.cfg marked read only, or a whole directory you do not own, stops the flow and says so in the log. Extracting into Program Files is the usual cause. Move the directory somewhere you own, clear the read-only flag, and start it again. If settings.cfg looks wrong afterwards, there is a settings.cfg.bak beside it holding the version before the last write.

A game whose site has no control panel yet never prints one, and its first grant is made with the tool instead. GM accounts covers both routes.

Accounts Do Not Work Between the Launcher and the Website

The launcher signs in through the game server and the GameCP signs in for itself, and the two are meant to read one accounts database. So this means they are not reading the same one. Almost always that is two settings.cfg files rather than two settings: a second copy of the server extracted somewhere else, or one of the two started next to a configuration of its own. A relative database path is measured from the directory holding the settings.cfg that was loaded, not from wherever the program happened to be launched, so the file each one found is the thing to check first. Both start-up logs name the database they opened.

Your Antivirus Flagged a File in the Download

You may see a binary from one of our archives quarantined as Trojan:Win32/Wacatac with an !ml on the end, usually by Windows Defender and usually at the moment you extract the zip.

It is a false positive, and the !ml is the part that says so. That suffix means the verdict came from a machine-learning model rather than from a signature that matched something known. That class of verdict is a well-known problem for exactly the kind of file we ship: small, statically linked Go executables, with no installer, no publisher signature and almost no users, which is a profile these models score badly whatever the program does.

Two different binaries of ours have drawn that name so far, on different machines and weeks apart, and both scanned clean afterwards with nothing about them changed. Expect it to move around rather than to settle on one file.

What to do about it:

1. Check the hash. Every release on this site publishes a SHA-256 beside the download. If your archive matches, you have the bytes we built.
2. Restore the file and exclude the server directory, or fetch the archive again and extract it somewhere excluded. A quarantined binary is simply missing, so the symptom is usually a server that will not start rather than a warning you remember seeing.
3. Tell us which file and which detection name, on Discord. It helps to know which one the model picked this time.

Nothing in our archives is packed, obfuscated or encrypted, which is worth saying because that is the usual reason a binary looks unusual to a scanner. We are working on the two things that genuinely fix this rather than explain it: signing our releases, and giving every shipped executable the version and publisher metadata these classifiers weigh. Until both are done, expect the occasional flag.

Where to Ask

Discord. Bring the version you are running, which we stamp into every archive name and print in the server log, and the first twenty lines of that log.