Skip to main content
The auto-pause feature monitors client connections and pauses the Java process when no players are connected. When a client attempts to connect, the process automatically resumes. This saves CPU resources without affecting the player experience.
As of Minecraft 1.21.2, the native pause-when-empty-seconds server property is recommended instead. Configure it using the PAUSE_WHEN_EMPTY_SECONDS environment variable.

​
Enabling Auto-Pause

Set the ENABLE_AUTOPAUSE environment variable to enable this feature: 
services:
  mc:
    image: itzg/minecraft-server
    environment:
      EULA: "TRUE"
      ENABLE_AUTOPAUSE: "true"
      MAX_TICK_TIME: "-1"  # Required!
    volumes:
      - ./data:/data
You must disable or greatly increase the max-tick-time watchdog. Set MAX_TICK_TIME=-1 to disable it entirely (highly recommended). From the server’s perspective, pausing causes a single tick to take a very long time, which can trigger the watchdog and force a container restart.

​
Watchdog Configuration

​
Vanilla Servers

For vanilla Minecraft servers, set MAX_TICK_TIME to -1: 
environment:
  ENABLE_AUTOPAUSE: "true"
  MAX_TICK_TIME: "-1"

​
PaperMC Servers

PaperMC has its own watchdog that must be disabled separately: 
environment:
  ENABLE_AUTOPAUSE: "true"
  MAX_TICK_TIME: "-1"
  JVM_DD_OPTS: "disable.watchdog:true"

​
Other Server Types

Check your server type’s documentation for watchdog configuration and disable it accordingly.

​
How Auto-Pause Works

1

Server starts

The server starts normally and waits for player connections.
2

Timeout period

If no players connect within the configured timeout, the Java process is paused.
3

Player attempts connection

When a player tries to connect, the knockd daemon detects the connection attempt at the network interface level.
4

Process resumes

The Java process is automatically resumed, and the player connects normally.

​
Configuration Variables

VariableDefaultDescription
AUTOPAUSE_TIMEOUT_EST3600Seconds between last client disconnect and pausing
AUTOPAUSE_TIMEOUT_INIT600Seconds between server start and pausing (if no connections)
AUTOPAUSE_TIMEOUT_KN120Seconds between port knock and pausing (if no connections)
AUTOPAUSE_PERIOD10Seconds between state machine checks
AUTOPAUSE_KNOCK_INTERFACEeth0Network interface for knock detection
AUTOPAUSE_STATUS_RETRY_LIMIT10Number of status check retries
AUTOPAUSE_STATUS_RETRY_INTERVAL2sTime between status check retries

​
Example Configuration

services:
  mc:
    image: itzg/minecraft-server
    environment:
      ENABLE_AUTOPAUSE: "true"
      MAX_TICK_TIME: "-1"
      AUTOPAUSE_TIMEOUT_EST: "1800"    # Pause after 30 min of no players
      AUTOPAUSE_TIMEOUT_INIT: "300"    # Pause after 5 min if no one joins
      AUTOPAUSE_TIMEOUT_KN: "60"       # Pause after 1 min of menu pings
      AUTOPAUSE_PERIOD: "5"            # Check every 5 seconds

​
Network Interface Configuration

The knock detection works at the network interface level. The correct interface must be configured for non-default networking:

​
Finding the Correct Interface

# Run ifconfig inside the container
docker exec mc ifconfig
Look for the interface receiving incoming connections and set it: 
environment:
  AUTOPAUSE_KNOCK_INTERFACE: "ens0"  # Use your interface name
Using the loopback interface (lo) will not work for knock detection.

​
Pause State Indicators

​
.paused File

When the server is paused, a .paused file is created in the /data directory: 
# Check if server is paused
docker exec mc test -f /data/.paused && echo "Paused" || echo "Running"
Other services can check for this file before attempting to wake the server.

​
.skip-pause File

Create a .skip-pause file to prevent auto-pausing: 
# Prevent auto-pause
docker exec mc touch /data/.skip-pause

# Re-enable auto-pause
docker exec mc rm /data/.skip-pause
The auto-pause timer resets when the .skip-pause file is present.

​
Rootless Auto-Pause

When running rootless containers, additional configuration is required:

​
Required Capabilities

Add the CAP_NET_RAW capability: 
services:
  mc:
    image: itzg/minecraft-server
    environment:
      ENABLE_AUTOPAUSE: "true"
      SKIP_SUDO: "true"
      MAX_TICK_TIME: "-1"
    cap_add:
      - CAP_NET_RAW

​
Port Forwarder Configuration

Change from RootlessKit to slirp4netns: Docker: 
docker run -d \
  -e ENABLE_AUTOPAUSE=true \
  -e AUTOPAUSE_KNOCK_INTERFACE=tap0 \
  --cap-add=CAP_NET_RAW \
  --network slirp4netns:port_handler=slirp4netns \
  itzg/minecraft-server
Podman: 
podman run -d \
  -e ENABLE_AUTOPAUSE=true \
  -e AUTOPAUSE_KNOCK_INTERFACE=tap0 \
  --cap-add=CAP_NET_RAW \
  --network slirp4netns:port_handler=slirp4netns \
  itzg/minecraft-server
See the setup guides:

​
Health Checks with Auto-Pause

When auto-pause is enabled, use the mc-health wrapper for health checks: 
services:
  mc:
    image: itzg/minecraft-server
    environment:
      ENABLE_AUTOPAUSE: "true"
      MAX_TICK_TIME: "-1"
    healthcheck:
      test: mc-health  # Not mc-status!
      start_period: 2m
      interval: 10s
Do not use mc-status directly. The mc-health wrapper correctly handles paused server states.
See the Health Checking page for more details.

​
Troubleshooting

​
Enable Debug Logging

Add debug output to troubleshoot issues: 
environment:
  ENABLE_AUTOPAUSE: "true"
  DEBUG_AUTOPAUSE: "true"

​
Common Issues

Server keeps restarting:
  • Ensure MAX_TICK_TIME=-1 is set
  • Check for other watchdog configurations in your server type
Auto-pause not triggering:
  • Verify the correct network interface is configured
  • Check the timeout values are appropriate
  • Enable debug logging to see state transitions
Knock detection not working:
  • Verify AUTOPAUSE_KNOCK_INTERFACE matches your network setup
  • Ensure CAP_NET_RAW is granted for rootless containers
  • Check that you’re not using the loopback interface

​
Example Compose File

A complete example is available in the GitHub repository. 
services:
  mc:
    image: itzg/minecraft-server
    ports:
      - "25565:25565"
    environment:
      EULA: "TRUE"
      ENABLE_AUTOPAUSE: "true"
      MAX_TICK_TIME: "-1"
      AUTOPAUSE_TIMEOUT_EST: "3600"
      AUTOPAUSE_TIMEOUT_INIT: "600"
      AUTOPAUSE_TIMEOUT_KN: "120"
    volumes:
      - ./data:/data
    healthcheck:
      test: mc-health
      start_period: 1m
      interval: 10s
    restart: unless-stopped

Build docs developers (and LLMs) love

Get started for freeTalk to us