Skip to content

Troubleshooting

Common issues and their solutions when running Minecraft Operator.

Server Issues

Server Not Starting

Symptoms: Pod stuck in Pending or CrashLoopBackOff

Check pod status:

kubectl describe pod survival-0 --namespace minecraft

Common causes:

Events:
  Warning  FailedScheduling  Insufficient memory

Solution: Reduce memory requests or add nodes:

spec:
  podTemplate:
    spec:
      containers:
        - name: minecraft
          resources:
            requests:
              memory: "1Gi"  # Reduce from 2Gi

Events:
  Warning  FailedMount  persistentvolumeclaim "data-survival-0" not found

Solution: Check StorageClass availability:

kubectl get storageclass
kubectl get pvc --namespace minecraft

Events:
  Warning  Failed  Failed to pull image

Solution: Check image name and registry access:

kubectl get papermcserver survival --namespace minecraft \
  --output jsonpath='{.status.desiredVersion}'

Server Crashes on Startup

Symptoms: Pod restarts repeatedly

Check logs:

kubectl logs survival-0 --namespace minecraft --previous

Common causes:

Look for OutOfMemoryError in logs.

Solution: Increase memory limits:

spec:
  podTemplate:
    spec:
      containers:
        - name: minecraft
          resources:
            limits:
              memory: "4Gi"  # Increase limit
          env:
            - name: JAVA_OPTS
              value: "-Xmx3G"  # Max heap < limit

Look for plugin errors in startup logs.

Solution: Temporarily remove plugins:

# Delete problematic plugin
kubectl delete plugin problematic-plugin --namespace minecraft

# Restart server
kubectl delete pod survival-0 --namespace minecraft

Look for RegionFileVersion or chunk errors.

Solution: Restore from backup or delete world:

# DANGER: This deletes the world
kubectl exec -it survival-0 --namespace minecraft -- rm -rf /data/world
kubectl delete pod survival-0 --namespace minecraft

Plugin Issues

Plugin Not Installing

Symptoms: Plugin shows Ready but not installed on server

Check plugin status:

kubectl get plugin essentialsx --namespace minecraft --output yaml

Common causes:

Plugin doesn't match server labels.

Check:

# Plugin selector
kubectl get plugin essentialsx --namespace minecraft \
  --output jsonpath='{.spec.instanceSelector}'

# Server labels
kubectl get papermcserver survival --namespace minecraft \
  --output jsonpath='{.metadata.labels}'

Solution: Fix labels or selector to match.

Plugin incompatible with server version.

Check:

kubectl get plugin essentialsx --namespace minecraft \
  --output jsonpath='{.status.matchedInstances}'

Solution: Use compatibility override or downgrade server:

spec:
  compatibilityOverride:
    enabled: true
    minecraftVersions:
      - "1.21.1"
      - "1.21.4"

Updates only apply during maintenance windows.

Check:

kubectl get papermcserver survival --namespace minecraft \
  --output jsonpath='{.spec.updateSchedule}'

Solution: Wait for maintenance window or force restart:

kubectl delete pod survival-0 --namespace minecraft

Plugin Download Failed

Symptoms: Plugin status shows errors

Check conditions:

kubectl get plugin bluemap --namespace minecraft \
  --output jsonpath='{.status.conditions}'

Common causes:

status:
  repositoryStatus: unavailable

Solution: Wait for Hangar to recover. Cached versions are used.

Operator cannot reach Hangar API.

Check operator logs:

kubectl logs deployment/minecraft-operator \
  --namespace minecraft-operator-system | grep -i hangar

Solution: Check network policies and egress rules.

Update Issues

Updates Blocked

Symptoms: updateBlocked: true in server status

Check reason:

kubectl get papermcserver survival --namespace minecraft \
  --output jsonpath='{.status.updateBlocked}'

Common causes:

updateBlocked:
  blocked: true
  reason: "Plugin incompatible with target version"
  blockedBy:
    plugin: "old-plugin"
    supportedVersions: ["1.20.4"]

Solution:

  1. Wait for plugin update
  2. Use compatibility override
  3. Remove incompatible plugin

All plugins together have no common compatible version.

Solution: Review plugin combinations and consider removing one.

Updates Not Happening

Symptoms: availableUpdate exists but not applied

Check schedule:

kubectl get papermcserver survival --namespace minecraft \
  --output jsonpath='{.spec.updateSchedule}'

Common causes:

Updates only apply during scheduled windows.

Check current cron:

spec:
  updateSchedule:
    maintenanceWindow:
      enabled: true
      cron: "0 4 * * 0"  # Sunday 4am only

updateDelay prevents immediate updates.

Check delay:

kubectl get papermcserver survival --namespace minecraft \
  --output jsonpath='{.spec.updateDelay}'

spec:
  updateSchedule:
    maintenanceWindow:
      enabled: false  # Updates disabled!

Operator Issues

Operator Not Running

Check deployment:

kubectl get deployment minecraft-operator \
  --namespace minecraft-operator-system

Check pod status:

kubectl describe pod -l app=minecraft-operator \
  --namespace minecraft-operator-system

Operator Errors

Check logs:

kubectl logs deployment/minecraft-operator \
  --namespace minecraft-operator-system \
  --tail=100

Common errors:

cannot list resource "papermcservers" in API group "mc.k8s.lex.la"

Solution: Reinstall or check RBAC:

kubectl get clusterrole minecraft-operator-manager-role --output yaml

no matches for kind "PaperMCServer" in version "mc.k8s.lex.la/v1alpha1"

Solution: Install CRD chart:

helm install minecraft-operator-crds \
  oci://ghcr.io/lexfrei/minecraft-operator-crds \
  --namespace minecraft-operator-system

Getting Help

If you can't resolve an issue:

  1. Check existing issues: GitHub Issues
  2. Create a new issue with:
  3. Operator version
  4. Kubernetes version
  5. Resource YAML (sanitized)
  6. Operator logs
  7. Pod events (kubectl describe pod)

See Also