Paper

The Maintenance plugin supports Paper servers with full feature support and Folia compatibility.

Requirements

Paper 1.20.1 or higher
Java 17 or higher

Version 5.0+ no longer supports Spigot. You must use Paper or a Paper fork.

Installation

Download the latest version from Hangar
Place the JAR file in your server’s plugins/ directory
Restart your server
Configure the plugin in plugins/Maintenance/config.yml

Folia Support

Maintenance is fully compatible with Folia, PaperMC’s new multithreaded server software.

Timer-based maintenance scheduling is not yet supported on Folia due to threading limitations.

Plugin Integrations

Maintenance integrates with several popular Paper plugins to enhance functionality.

ServerListPlus

Soft dependency - Automatically detected if installed. When ServerListPlus is present, Maintenance can control its status based on maintenance mode:

ServerListPlus is disabled when maintenance is enabled
ServerListPlus is re-enabled when maintenance is disabled

This integration is controlled by the enable-pingmessages config option.

ProtocolLib

Soft dependency - Optional enhancement. ProtocolLib provides additional packet-level control for advanced server list customization.

LuckPerms

Soft dependency - Context support. Maintenance registers a maintenance context with LuckPerms, allowing you to create permissions that are conditional on maintenance status.

Features

Custom Server List

Customize your server list appearance during maintenance:

Custom MOTD - Display a maintenance message in the server list
Custom Icon - Show a different server icon during maintenance
Player Count Message - Customize the player count display

Maintenance Whitelist

Allow specific players to join during maintenance:

/maintenance add <player>
/maintenance remove <player>

Whitelisted players bypass the maintenance kick and can join normally.

Scheduled Maintenance

Schedule maintenance windows with timers:

# Start maintenance in 1 hour
/maintenance start 1h

# End maintenance in 30 minutes
/maintenance end 30m

Use the %TIMER% placeholder in your MOTD to display remaining time.

Player Kick

When maintenance is enabled, players without bypass permission are automatically kicked with a configurable message. Players with the maintenance.bypass permission can join during maintenance.

Configuration

The main configuration file is located at plugins/Maintenance/config.yml. Key configuration options:

maintenance: false              # Enable/disable maintenance mode
enable-pingmessages: true       # Show custom MOTD during maintenance
kick-players: true              # Kick players when enabling maintenance
whitelisted-players: []         # List of whitelisted player UUIDs

Icon Setup

Place your custom maintenance icon at plugins/Maintenance/maintenance-icon.png:

Must be 64x64 pixels
PNG format
Will be displayed during maintenance mode

Permissions

Permission	Description
`maintenance.command`	Access to `/maintenance` command
`maintenance.bypass`	Join server during maintenance
`maintenance.admin`	Full administrative access
`maintenance.joinnotification`	Receive notifications when players try to join

Commands

All commands use the base command /maintenance or /mt.

/maintenance on              # Enable maintenance mode
/maintenance off             # Disable maintenance mode
/maintenance add <player>    # Add player to whitelist
/maintenance remove <player> # Remove player from whitelist
/maintenance start <time>    # Schedule maintenance start
/maintenance end <time>      # Schedule maintenance end
/maintenance reload          # Reload configuration

Unsupported Features

The following features are only available on proxy platforms (BungeeCord/Velocity):

Redis integration for multi-proxy setups
Per-server maintenance mode
Fallback server configuration
Waiting server functionality

API Usage

Developers can integrate with Maintenance using the API:

import eu.kennytv.maintenance.api.Maintenance;
import eu.kennytv.maintenance.api.MaintenanceProvider;

public class YourPlugin extends JavaPlugin {
    private Maintenance maintenance;

    @Override
    public void onEnable() {
        // Get Maintenance API
        maintenance = MaintenanceProvider.get();
        
        // Check if maintenance is enabled
        boolean isMaintenance = maintenance.isMaintenance();
        
        // Enable/disable maintenance
        maintenance.setMaintenance(true);
    }
}

See the API documentation for more details.

Troubleshooting

Players can still join during maintenance

Check that:

Players don’t have the maintenance.bypass permission
Players are not on the whitelist (/maintenance remove <player>)
Maintenance is actually enabled (/maintenance on)

Custom icon not showing

Ensure:

Icon is 64x64 pixels and PNG format
File is located at plugins/Maintenance/maintenance-icon.png
Server has been restarted after adding the icon

Timer not working

On Folia servers, timer-based maintenance is not yet supported. Use manual commands instead.

Get Started

Configuration

Platform Guides

Features

Commands & Permissions

Requirements

Installation

Folia Support

Plugin Integrations

ServerListPlus

ProtocolLib

LuckPerms

Features

Custom Server List

Maintenance Whitelist

Scheduled Maintenance

Player Kick

Configuration

Icon Setup

Permissions

Commands

Unsupported Features

API Usage

Troubleshooting

Players can still join during maintenance

Custom icon not showing

Timer not working

​Requirements

​Installation

​Folia Support

​Plugin Integrations

​ServerListPlus

​ProtocolLib

​LuckPerms

​Features

​Custom Server List

​Maintenance Whitelist

​Scheduled Maintenance

​Player Kick

​Configuration

​Icon Setup

​Permissions

​Commands

​Unsupported Features

​API Usage

​Troubleshooting

​Players can still join during maintenance

​Custom icon not showing

​Timer not working

Requirements

Installation

Folia Support

Plugin Integrations

ServerListPlus

ProtocolLib

LuckPerms

Features

Custom Server List

Maintenance Whitelist

Scheduled Maintenance

Player Kick

Configuration

Icon Setup

Permissions

Commands

Unsupported Features

API Usage

Troubleshooting

Players can still join during maintenance

Custom icon not showing

Timer not working