Skip to main content

​
Introduction

The Maintenance plugin uses a YAML configuration file to control all aspects of maintenance mode, from server messages to Redis synchronization. This page provides an overview of the configuration system and how to manage your settings.

​
Configuration File Location

The main configuration file is located at:
  • Bukkit/Spigot/Paper: plugins/Maintenance/config.yml
  • BungeeCord/Velocity: plugins/Maintenance/config.yml
Additional configuration files:
  • WhitelistedPlayers.yml - Stores players allowed to join during maintenance
  • maintenance-icon.png - Custom server icon displayed during maintenance (optional)

​
Reloading Configuration

To reload the configuration after making changes, use: 
/maintenance reload
This command requires the maintenance.reload permission.

​
Configuration Sections

The configuration is organized into several sections:

Maintenance Messages

Configure MOTD, player count, and hover messages displayed during maintenance

Timers

Set up automatic maintenance scheduling and timer broadcasts

Whitelist

Manage players allowed to join during maintenance mode

Redis

Synchronize maintenance status across multiple proxy instances

Languages

Change the plugin language and contribute translations

​
Basic Settings

​
maintenance-enabled
boolean
default:"false"
Enables or disables maintenance mode globally.
​
proxied-maintenance-servers
array
List of specific servers to enable maintenance on when using a proxy.
proxied-maintenance-servers:
  - PaperServer1
  - AnotherServer
​
fallback
string | array
default:"lobby"
Server to send players to when maintenance is enabled on a proxied server. Can be a single server or an array of fallback servers.
fallback: lobby
# OR
fallback: [lobby1, lobby2, lobby3]
​
waiting-server
string
default:""
A “waiting” lobby server for players to be sent to during global maintenance instead of being kicked. Leave empty to disable.
​
kick-online-players
boolean
default:"true"
If set to false, players will not be kicked when maintenance is enabled (new connections will still be blocked).
​
send-join-notification
boolean
default:"false"
If enabled, players with the maintenance.joinnotification permission will receive a message when someone tries to join during maintenance.
​
custom-maintenance-icon
boolean
default:"false"
If enabled, the server icon will be changed to maintenance-icon.png from the plugin’s folder during maintenance.
​
fallback-to-offline-uuid
boolean
default:"false"
When fetched player does not exist, fallback to offline UUID. Only works on proxies like Velocity or BungeeCord.
​
update-checks
boolean
default:"true"
Enables automatic update notifications. You can always check manually using /maintenance update.

​
Command Execution

You can configure commands to run automatically when maintenance is enabled or disabled:
​
commands-on-maintenance-enable
array
Commands executed when maintenance is enabled globally.
commands-on-maintenance-enable:
  - "say Maintenance mode enabled!"
  - "broadcast Server going down for maintenance"
​
commands-on-maintenance-disable
array
Commands executed when maintenance is disabled globally.
commands-on-maintenance-disable:
  - "say Maintenance mode disabled!"
  - "broadcast Server is now online!"
​
commands-on-single-maintenance-enable
object
Commands executed when maintenance is enabled on a specific proxied server. Use %SERVER% placeholder for the server name.
commands-on-single-maintenance-enable:
  all:
    - "alert %SERVER% is now under maintenance"
  PaperServer1:
    - "say PaperServer1 maintenance started"
​
commands-on-single-maintenance-disable
object
Commands executed when maintenance is disabled on a specific proxied server.
commands-on-single-maintenance-disable:
  all:
    - "alert %SERVER% is now online"

​
Text Formatting

All messages in the configuration use MiniMessage format, NOT legacy color codes. Use the MiniMessage Web UI to create and preview formatted text.
Some fields (like player-count-message and player-list-hover-message) do not support RGB colors due to Minecraft protocol limitations.

Build docs developers (and LLMs) love

Get started for freeTalk to us