Skip to main content
This guide will help you get Maintenance up and running on your server quickly. If you haven’t installed the plugin yet, check out the installation guide first.

​
Enable maintenance mode

Once installed, enabling maintenance mode is as simple as running a single command: 
/maintenance on
All players without permission will be kicked from the server, and new connections will be blocked until you disable maintenance mode. To disable maintenance mode: 
/maintenance off
You can use /mt as a shortcut for /maintenance

​
Managing the whitelist

During maintenance, you’ll likely want to allow specific players (like staff members) to join. Add players to the maintenance whitelist: 
/maintenance add PlayerName
To remove a player from the whitelist: 
/maintenance remove PlayerName
View all whitelisted players: 
/maintenance whitelist
Whitelisted players can join even when maintenance mode is enabled. They need the maintenance.bypass permission to bypass the maintenance screen.

​
Schedule maintenance with timers

Instead of manually enabling and disabling maintenance, you can schedule it with timers:

​
End timer

Schedule maintenance to automatically disable after a certain time: 
# Disable maintenance in 30 minutes
/maintenance endtimer 30m

# Disable in 2 hours and 30 minutes
/maintenance endtimer 2h30m

# Disable in 90 seconds
/maintenance endtimer 90s
The %TIMER% placeholder in your MOTD will show the remaining time.

​
Start timer

Schedule maintenance to enable after a certain time: 
# Enable maintenance in 1 hour
/maintenance starttimer 1h

​
Cancel a timer

If you need to cancel a running timer: 
/maintenance aborttimer

​
Customize maintenance messages

Edit the config.yml file in your plugin folder to customize the message shown during maintenance:
config.yml
ping-message:
  enabled: true
  messages:
    - "<red>Currently under maintenance<br><gradient:#fbffc2:#0fffff>We will be back soon!"
Maintenance uses MiniMessage formatting, which supports:
  • Colors: <red>, <blue>, <#FF5555>
  • Gradients: <gradient:#fbffc2:#0fffff>text</gradient>
  • Decorations: <bold>, <italic>, <underlined>
  • And much more!
After editing the config, reload it with: 
/maintenance reload
Make sure to test your MiniMessage formatting at https://webui.advntr.dev/ before applying it!

​
Proxy-specific features (BungeeCord/Velocity)

If you’re using BungeeCord or Velocity, you can enable maintenance on individual backend servers: 
# Enable maintenance on a specific server
/maintenance on servername

# Disable maintenance on a specific server
/maintenance off servername
Players on a server when maintenance is enabled will be sent to your configured fallback server instead of being kicked.

​
Next steps

Configuration

Learn about all configuration options

Commands Reference

Explore all available commands

Platform Guides

Platform-specific setup guides

API Integration

Integrate with your own plugins

​
Common tasks

  1. Create a 64x64 PNG image named maintenance-icon.png
  2. Place it in your plugin’s folder (plugins/Maintenance/ or plugins/maintenance/)
  3. Enable it in config.yml:
custom-maintenance-icon: true
  1. Reload the config: /maintenance reload
  1. Start an endtimer: /maintenance endtimer 30m
  2. Use the %TIMER% placeholder in your MOTD configuration:
ping-message:
  enable-timer-specific-messages: true
  timer-messages:
    - "<red>Maintenance ends in: <yellow>%TIMER%"
Grant them the maintenance.bypass permission and add them to the whitelist:
/maintenance add StaffMemberName
They’ll be able to join even during maintenance mode.
Set up Redis synchronization in your config.yml:
redis:
  enabled: true
  uri: "redis://localhost:6379"
All proxies connected to the same Redis instance will automatically sync maintenance status and whitelists. See the Redis configuration guide for details.

Build docs developers (and LLMs) love

Get started for freeTalk to us