Health Checking

Configure and monitor Minecraft server health checks using mc-monitor and mc-health

The Minecraft server image includes mc-monitor for health checking. Health checks allow Docker and orchestration systems to monitor server status and automatically restart unhealthy containers.

Default Health Check

The image includes a built-in health check that continuously monitors the server status:

# View container health status
docker ps

Example output:

CONTAINER ID   IMAGE   COMMAND    CREATED         STATUS                   PORTS                      NAMES
b418af073764   mc      "/start"   43 seconds ago  Up 41 seconds (healthy)  0.0.0.0:25565->25565/tcp   mc

Checking Health Status

Using Docker Inspect

Query the container’s health status programmatically:

docker container inspect -f "{{.State.Health.Status}}" mc

Output:

healthy

Possible values:

• healthy - Server is running and responding
• unhealthy - Server is not responding
• starting - Server is still starting up

Using mc-health Wrapper

The mc-health script wraps mc-monitor status with the correct arguments:

# Execute health check inside container
docker exec mc mc-health

Custom Health Check Configuration

You can customize health check parameters in a Docker Compose file:

services:
  mc:
    image: itzg/minecraft-server
    environment:
      EULA: "TRUE"
    ports:
      - "25565:25565"
    volumes:
      - ./data:/data
    healthcheck:
      test: mc-health
      start_period: 1m
      interval: 5s
      retries: 20
      timeout: 10s

Health Check Parameters

Parameter	Description	Default
test	Command to run for health check	mc-health
start_period	Grace period before health checks begin	1m
interval	Time between health checks	5s
retries	Number of consecutive failures before unhealthy	20
timeout	Maximum time for health check to complete	10s

Disabling Health Checks

Using Environment Variable

Some orchestration systems (like Portainer) don’t allow disabling the default health check. Use the environment variable:

services:
  mc:
    image: itzg/minecraft-server
    environment:
      DISABLE_HEALTHCHECK: "true"

Using Docker Compose

Disable health checks directly in the service declaration:

services:
  mc:
    image: itzg/minecraft-server
    healthcheck:
      disable: true
      test: ["NONE"]

Health Checks with Auto-Pause

When using the auto-pause feature, reference the mc-health wrapper instead of mc-status directly:

services:
  mc:
    image: itzg/minecraft-server
    environment:
      ENABLE_AUTOPAUSE: "true"
      MAX_TICK_TIME: "-1"
    healthcheck:
      test: mc-health  # Important: use mc-health, not mc-status
      start_period: 2m
      interval: 10s

When auto-pause is enabled, the server may be in a paused state. The mc-health script correctly handles paused servers, while direct mc-status calls may report false negatives.

Health Checks for Older Versions

Health checks are automatically disabled for Minecraft versions before Beta 1.8, as these versions don’t support server pinging.

Versions before Beta 1.8 lack the Server List Ping protocol. See the Minecraft Wiki for more information.

Kubernetes Health Checks

For Kubernetes deployments, configure liveness and readiness probes:

apiVersion: v1
kind: Pod
metadata:
  name: minecraft
spec:
  containers:
  - name: minecraft
    image: itzg/minecraft-server
    env:
    - name: EULA
      value: "TRUE"
    livenessProbe:
      exec:
        command:
        - mc-health
      initialDelaySeconds: 60
      periodSeconds: 10
      failureThreshold: 3
    readinessProbe:
      exec:
        command:
        - mc-health
      initialDelaySeconds: 30
      periodSeconds: 5
      failureThreshold: 2

Monitoring Health Check Logs

View detailed health check logs:

# View health check output
docker inspect mc | jq '.[0].State.Health'

Example output:

{
  "Status": "healthy",
  "FailingStreak": 0,
  "Log": [
    {
      "Start": "2026-03-01T10:30:00.000000000Z",
      "End": "2026-03-01T10:30:01.000000000Z",
      "ExitCode": 0,
      "Output": "Server is healthy"
    }
  ]
}

Troubleshooting

Health Check Failing on Startup

Increase the start_period to give the server more time to start:

healthcheck:
  test: mc-health
  start_period: 3m  # Increase for modded servers
  interval: 10s

Intermittent Health Check Failures

Adjust retry count and interval:

healthcheck:
  test: mc-health
  interval: 15s     # Check less frequently
  retries: 5        # Allow more retries
  timeout: 30s      # Longer timeout

Health Check Not Working

Verify mc-monitor is working:

# Test mc-monitor directly
docker exec mc mc-monitor status

# Check mc-health script
docker exec mc which mc-health

Best Practices

1. Use mc-health wrapper instead of calling mc-monitor directly
2. Increase start_period for modded servers (2-5 minutes)
3. Configure appropriate timeouts based on server performance
4. Monitor health check logs during initial setup
5. Disable health checks only when absolutely necessary
6. Use with restart policies for automatic recovery

services:
  mc:
    image: itzg/minecraft-server
    restart: unless-stopped
    healthcheck:
      test: mc-health
      start_period: 2m
      interval: 10s
      retries: 3