Reference
Troubleshooting
What Link's log messages mean and how to fix the common problems.
Start with /link on the server that has the problem. It shows whether Link is
running, whether the registry answers and whether transfers are ready.
Warnings at startup
When link.json is incomplete, Link logs what is missing, then
Transfers are off until link.json is fixed. Fix the file and restart.
| Message | Fix |
|---|---|
this server (<id>) is not in the servers list | With a shared file, add this server to servers, or correct serverId or LINK_SERVER_ID. |
backend is REDIS but redis.url is empty | Set redis.url or LINK_REDIS_URL. |
backend is HTTP but http.url or http.token is empty | Set both, or LINK_HTTP_URL and LINK_HTTP_TOKEN. |
host is empty; other servers need it to send players here | Set host or LINK_HOST to an address players can reach. |
serverId is empty or group is empty | Give the server a name and a group. |
Could not read link.json | The file is not valid JSON. Check for a missing comma or quote. |
Players get “Transfers are not available yet”
The server has not reached the registry since it started, so it doesn’t have
the network secret yet. Check that it can reach your Redis or Worker, and that
the password or token is right. The log shows Registry unreachable with the
reason.
Players are moved but land as a normal join
The target logs Refused a transfer ticket from <player>. Usually:
- The secret is different. With a shared file, every server must have the same
secret. With Redis, every server must use the samenamespace. - The clocks are far apart. Tickets allow 10 seconds of difference. Turn on time sync (NTP) on your machines.
- The server names don’t match. The target’s
serverIdmust be the id the other servers know it by.
Players can’t connect after a transfer
Link sent them, but their game can’t reach the target’s host and port.
These must be reachable from the player’s computer: a public address or domain,
not 127.0.0.1 or a private address, unless your players are on the same
network.
/play always picks the same server
- With a shared file, there are no player counts, so Link takes turns. That is expected.
- With
fill, Link fills the busiest server first on purpose. Usespreadon lobbies. See matchmaking.
Still stuck?
Open an issue with the output
of /link and the [Link] lines from both servers’ logs. Remove your secret,
passwords and tokens first.