Skip to main content
The Maintenance plugin supports Velocity, the modern, high-performance Minecraft proxy from PaperMC.

​
Requirements

  • Velocity 3.0 or higher
  • Java 17 or higher

​
Installation

  1. Download the latest version from Hangar
  2. Place the JAR file in your Velocity plugins/ directory
  3. Restart your proxy
  4. Configure the plugin in plugins/maintenance/config.yml

​
Why Velocity?

Velocity offers several advantages over BungeeCord:
  • Better performance - More efficient packet handling and threading
  • Modern API - Built on contemporary Java practices
  • Native Adventure support - Full rich text formatting
  • Active development - Regular updates from the Paper team
Maintenance takes full advantage of Velocity’s modern architecture.

​
Proxy Features

Velocity installation provides the same advanced features as BungeeCord:

​
Global Maintenance

Enable maintenance for your entire network: 
/maintenance on
Prevents all players (without bypass permission) from connecting.

​
Per-Server Maintenance

Enable maintenance for individual backend servers: 
/maintenance on <server>
/maintenance off <server>
Players connecting to a server under maintenance will be:
  • Redirected to a fallback server (if configured)
  • Disconnected with a custom message (if no fallback)

​
Fallback Server Configuration

Configure fallback servers in config.yml: 
fallback:
  enabled: true
  fallback-list:
    survival: lobby
    creative: hub
    skyblock: lobby
When a player tries to join a maintenance server, they’re automatically sent to the fallback.

​
Waiting Server

Direct all players to a waiting lobby during global maintenance: 
waiting-server:
  enabled: true
  server: waiting
Instead of kicking players, they’ll be sent to your waiting lobby.

​
Redis Integration

Sync maintenance status across multiple Velocity proxies: 
redis:
  enabled: true
  host: localhost
  port: 6379
  password: ""
  channel: maintenance
Essential for multi-proxy networks to keep maintenance status synchronized.

​
Plugin Integrations

​
ServerListPlus

Optional dependency - Automatically detected. Enhances server list customization during maintenance mode. Maintenance will automatically disable ServerListPlus when maintenance is enabled.

​
LuckPerms

Optional dependency - Context support. Maintenance registers maintenance contexts with LuckPerms, allowing you to create conditional permissions.

​
Velocity-Specific Features

​
Native Adventure Components

Velocity has native support for Adventure text components. All messages in Maintenance use Adventure’s Component API:
  • Full RGB color support
  • Hover events
  • Click events
  • Rich formatting options
Configure messages using MiniMessage format: 
kick-message: "<red><bold>Server is under maintenance!<br><gray>Check back soon."

​
Async Event Handling

Velocity’s event system is fully asynchronous. Maintenance leverages this for optimal performance:
  • Non-blocking player connection checks
  • Efficient server switching
  • Better scalability

​
Config Reload Support

Velocity supports native plugin reloading: 
/maintenance reload
Or use Velocity’s native reload: 
/velocity reload
Maintenance will automatically reload its configuration.

​
Configuration

Velocity configuration is similar to BungeeCord with some differences: 
# Global maintenance
maintenance: false

# Per-server maintenance
proxied-maintenance-servers:
  lobby: false
  survival: false

# Fallback configuration
fallback:
  enabled: true
  fallback-list:
    survival: lobby

# Waiting server
waiting-server:
  enabled: false
  server: waiting

# Redis for multi-proxy setups
redis:
  enabled: false
  host: localhost
  port: 6379
  password: ""
  channel: maintenance

# Server list customization
playercountmessage: "Maintenance Mode"
enable-timerspecific-playercountmessage: false
timer-playercountmessage: "Back in %TIMER%"

​
Permissions

PermissionDescription
maintenance.commandAccess to /maintenance command
maintenance.bypassJoin during maintenance
maintenance.adminFull administrative access
maintenance.joinnotificationReceive join attempt notifications
Configure permissions using your Velocity-compatible permissions plugin (e.g., LuckPerms).

​
Commands

All commands are available under /maintenance or /mt: 
# Global maintenance
/maintenance on                    # Enable global maintenance
/maintenance off                   # Disable global maintenance

# Per-server maintenance
/maintenance on <server>           # Enable for specific server
/maintenance off <server>          # Disable for specific server

# Whitelist
/maintenance add <player>          # Add to whitelist
/maintenance remove <player>       # Remove from whitelist

# Timers
/maintenance start <time>          # Schedule start (e.g., 1h, 30m)
/maintenance end <time>            # Schedule end

# Management
/maintenance reload                # Reload configuration

​
Server List Customization

​
Custom MOTD

Use MiniMessage format for rich text: 
motd:
  maintenance:
    - "<gradient:red:gold>Server Maintenance</gradient>"
    - "<gray>We'll be back soon!"

​
Custom Icon

Place your maintenance icon at plugins/maintenance/maintenance-icon.png:
  • 64x64 pixels
  • PNG format

​
Player Count Message

playercountmessage: "Under Maintenance"
With timer: 
enable-timerspecific-playercountmessage: true
timer-playercountmessage: "Restarting: %TIMER%"

​
Migration from BungeeCord

Migrating from BungeeCord to Velocity is straightforward:
  1. Install Velocity and configure your servers
  2. Copy your Maintenance config from BungeeCord
  3. Update server names if they changed
  4. Restart Velocity
All configuration options are compatible between platforms.

​
Multi-Proxy Setup

For networks with multiple Velocity proxies:
  1. Deploy Redis server
  2. Configure Redis on all proxies:
redis:
  enabled: true
  host: redis.example.com
  port: 6379
  password: "secure-password"
  channel: maintenance-network
  1. Reload all proxies
Maintenance status will now sync across all proxies in real-time.

​
API Usage

For Velocity plugin developers: 
import eu.kennytv.maintenance.api.proxy.MaintenanceProxy;
import eu.kennytv.maintenance.api.MaintenanceProvider;
import com.velocitypowered.api.plugin.Plugin;
import com.google.inject.Inject;

@Plugin(id = "yourplugin")
public class YourPlugin {
    private MaintenanceProxy maintenance;

    @Inject
    public YourPlugin() {
        // Get Maintenance API
        maintenance = (MaintenanceProxy) MaintenanceProvider.get();
        
        // Check global maintenance
        if (maintenance.isMaintenance()) {
            // Handle maintenance mode
        }
        
        // Check server-specific maintenance
        if (maintenance.isMaintenance("survival")) {
            // Survival server is in maintenance
        }
    }
}
See the API documentation for complete reference.

​
Troubleshooting

​
Plugin not loading

Check:
  1. You’re running Velocity 3.0 or higher
  2. Java 17+ is installed
  3. JAR file is in the plugins/ directory
  4. Check Velocity console for errors

​
Fallback not working

Ensure:
  1. Fallback server exists in Velocity’s velocity.toml
  2. Fallback server is not in maintenance
  3. Player has permission to access fallback server
  4. Fallback is correctly configured in maintenance config

​
Redis not syncing

Verify:
  1. Redis server is accessible from all proxies
  2. Same Redis credentials on all proxies
  3. Same channel name on all proxies
  4. Check logs for connection errors
  5. Test Redis connection independently

​
Messages not displaying correctly

Velocity uses MiniMessage format:
  • Use <red> not §c
  • Use <br> for line breaks
  • See MiniMessage docs for formatting

Build docs developers (and LLMs) love

Get started for freeTalk to us