Help

Troubleshooting

Where to look when a resource doesn't do what you expect, and fixes for common problems.

Where to look first

Most problems explain themselves if you know where to look:

  1. The resource’s status. kubectl get <kind> <name> shows the phase, and status.message often says exactly what the resource is waiting for.
  2. Events. kubectl describe <kind> <name> lists recent events at the bottom, including reasons why the operator couldn’t continue.
  3. Pod logs. For servers: kubectl logs <server>-0 -c server. For anything that runs as a Job, such as backups and account sign-ins, look at the job’s pod.
  4. The operator’s logs. kubectl -n kobblestone-system logs deployment/kobblestone for a Helm release named kobblestone, or deployment/kobblestone-operator if you installed the plain manifest.

Servers

The server stays in Starting

The first start downloads the server software, plugins and mods, and generates the world. Depending on the server type and your connection, that can take several minutes. The server log shows the progress.

If the server keeps restarting, it might not finish starting within spec.timeouts.maxStartupTimeSeconds (360 seconds by default). Large modpacks often need more.

The server pod is Pending

Usually its volume can’t be created or attached. Check the PersistentVolumeClaim with kubectl describe pvc <server>: there may be no default StorageClass, or the requested storageClassName doesn’t exist. Also make sure a node has enough free memory for the server’s resource requests.

The server is killed or restarts under load

If the pod shows OOMKilled, the server needs more memory than its limit. Raise spec.resources.limits.memory, or lower spec.jvm.memory.heapPercentage to leave more room for the JVM outside the heap.

Changes to the spec don’t apply

If spec.lifecycle.rolloutPolicy is Manual, changes only apply when the server pod is recreated, for example after stopping and starting the server.

Connecting

Players can’t connect through a Router

  • Check the Router’s spec.hostnames. An empty list accepts no hostnames at all; use "*" to accept any.
  • Check that the hostname resolves to the Router’s address (status.address, or the Address column of kubectl get routers).
  • kubectl get routes shows each route’s Router and resolved backend. A route without a backend address points at something that doesn’t exist or isn’t ready.
  • The Router accepts only one new connection per second by default. If several players join at once, raise spec.networking.maxConnectionsPerSecond.

A hibernating server doesn’t wake up

Servers in Hibernate mode only start again when a player connects through a Router. Direct connections, port forwards and LoadBalancer services don’t wake them up.

Commands and backups

Commands fail

Commands need RCON. Check that spec.rcon.disabled isn’t true on the server and that the server is running. status.failureReason and status.message of the command tell you more. If the operator can’t reach the server inside the cluster, try trafficPolicy: External.

A backup or restore stays Pending

status.message says what it is waiting for. Common reasons:

  • The BackupRepo or the server doesn’t exist, or the server has no storage.
  • Another backup or restore of the same server is still running. They run one after another.
  • The repository is a volume without ReadWriteMany that is in use by another operation.
  • For a restore: the server isn’t stopped yet. Set its spec.state to Stopped.

Accounts and bots

The account stays Unauthorized

status.message contains the reason, for example an expired device code or a Microsoft account without a Minecraft profile. Kobblestone starts a new sign-in after 10 minutes. Check that spec.inactive isn’t true.

The bot stays Pending

A bot with an Account waits until the account is Authorized. Check the account first.

The bot keeps disconnecting

status.message holds the reason of the last disconnect, such as a kick message or a rejected login. Online servers need a bot with an authorized account; offline-mode servers need offlineUsername or no auth at all.

Still stuck?

Open an issue on GitHub with the resource manifest, its status and events, the operator logs and your Kubernetes version.