Troubleshooting

Logs

On the Controller’s machine:

cd /opt/shardkeep
docker compose logs controller   # the Controller
docker compose logs agent        # the bundled Agent

On another Node: docker logs shardkeep-agent.

I lost the setup code

Print it again: docker compose exec controller shardkeep admin setup-code. If it says there is no code, setup is already done: sign in, or use shardkeep admin reset-password.

A Node will not enroll

• The token was used or expired. Tokens work once, within the hour. On the Node’s page, issue a new one.
• The Agent cannot reach the Controller. It needs ports 8443 and 8444 on the address in its -controller flag. Test from the Node with nc -vz <controller> 8443.
• The name is not on the Controller’s certificate. The Controller presents a certificate for its -public-name names. Use one of them in -controller, or add the name you use with -public-name (in the Compose install, SHARDKEEP_PUBLIC_NAME).

A Node shows as unreachable

Its Agent stopped sending heartbeats. Check that shardkeep-agent is running on it and can reach port 8443. Its servers keep running meanwhile; see When the Controller is down.

A server stays stopped or keeps crashing

Look at its Overview for a condition, then its Console and Activity. Common causes: too little memory for its plugins, a plugin that does not support its Minecraft version, or a broken configuration file.

Players cannot join through the network

• The network’s address must point at the public IP of the Node running the proxy, and its port must be open (forwarded on your router if needed).
• Servers on other Nodes must be reachable from the proxy’s Node on their game ports. Check each Node’s address on its page.
• Joining a server’s own port directly is refused when it is in the network. That is intended.

The catalog does not sync

The Controller logs a warning when a sync fails. It needs HTTPS access to catalog.shardkeep.gg. Servers keep working with what is cached.

Still stuck?

See Getting help.