Skip to main content
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

  1. Download the latest version from Hangar
  2. Place the JAR file in your server’s plugins/ directory
  3. Restart your server
  4. 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

PermissionDescription
maintenance.commandAccess to /maintenance command
maintenance.bypassJoin server during maintenance
maintenance.adminFull administrative access
maintenance.joinnotificationReceive 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:
  1. Players don’t have the maintenance.bypass permission
  2. Players are not on the whitelist (/maintenance remove <player>)
  3. Maintenance is actually enabled (/maintenance on)

​
Custom icon not showing

Ensure:
  1. Icon is 64x64 pixels and PNG format
  2. File is located at plugins/Maintenance/maintenance-icon.png
  3. 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us