Skip to main content

​
Overview

The whitelist feature allows specific players to join the server even when maintenance mode is enabled. This is useful for administrators, moderators, and other trusted players who need access during maintenance.

​
WhitelistedPlayers.yml

Whitelisted players are stored in the WhitelistedPlayers.yml file, located in the plugin’s data folder:
  • Bukkit/Spigot/Paper: plugins/Maintenance/WhitelistedPlayers.yml
  • BungeeCord/Velocity: plugins/Maintenance/WhitelistedPlayers.yml

​
File Structure

The file uses a simple UUID-to-username mapping format: 
# UUID: username
a8179ff3-c201-4a75-bdaa-9d14aca6f83f: kennytv
12345678-1234-1234-1234-123456789abc: Notch
87654321-4321-4321-4321-cba987654321: Dinnerbone

​
Manual Editing

You can manually add or remove players by editing this file:
  1. Open WhitelistedPlayers.yml in a text editor
  2. Add entries in the format uuid: username
  3. Save the file
  4. Reload the plugin: /maintenance reload
Ensure UUIDs are valid and formatted correctly. Invalid entries may cause errors or be ignored.

​
Whitelist Commands

The recommended way to manage the whitelist is through commands, as they handle UUID lookups automatically.

​
Add Player to Whitelist

Add a player to the whitelist using their username or UUID: 
# Add by username
/maintenance add kennytv

# Add by UUID
/maintenance add a8179ff3-c201-4a75-bdaa-9d14aca6f83f
Permission: maintenance.add When adding by username, the plugin will automatically fetch the player’s UUID from Mojang’s servers.

​
Remove Player from Whitelist

Remove a player from the whitelist: 
# Remove by username
/maintenance remove kennytv

# Remove by UUID
/maintenance remove a8179ff3-c201-4a75-bdaa-9d14aca6f83f
Permission: maintenance.remove

​
List Whitelisted Players

View all whitelisted players: 
/maintenance list
Permission: maintenance.list This command displays all whitelisted players with their usernames and UUIDs.

​
UUID Handling

The plugin handles both online and offline mode UUIDs:
​
fallback-to-offline-uuid
boolean
default:"false"
When enabled, if a player UUID cannot be fetched from Mojang’s servers, the plugin will fallback to using an offline-mode UUID.This only works on proxy servers (Velocity or BungeeCord).
fallback-to-offline-uuid: false

​
Online Mode (Default)

In online mode, the plugin fetches UUIDs from Mojang’s authentication servers. This is the most reliable method for online-mode servers.

​
Offline Mode

For offline-mode servers or when the Mojang API is unavailable, enable fallback-to-offline-uuid: 
fallback-to-offline-uuid: true
Offline UUIDs are generated differently than online UUIDs. A player will have different UUIDs in online vs offline mode.

​
Permissions

Whitelist-related permissions:
PermissionDescription
maintenance.bypassAllows players to join during maintenance without being on the whitelist
maintenance.addAllows adding players to the whitelist
maintenance.removeAllows removing players from the whitelist
maintenance.listAllows viewing the whitelist

​
Bypass Permission

Instead of adding players to the whitelist, you can grant the maintenance.bypass permission: 
permissions:
  maintenance.bypass:
    description: Allows joining during maintenance
    default: op
Players with this permission can join during maintenance without being explicitly added to the whitelist.

​
Redis Synchronization

If you’re using Redis for multi-proxy setups, whitelist changes are automatically synchronized across all connected proxy instances. When you add or remove a player on one proxy:
  1. The change is saved to WhitelistedPlayers.yml locally
  2. The change is published to Redis
  3. Other proxy instances receive the update
  4. All proxies update their whitelists automatically
See the Redis Configuration page for more details.

​
Example Workflow

​
Adding Multiple Staff Members

# Add administrators
/maintenance add Admin1
/maintenance add Admin2

# Add moderators
/maintenance add Moderator1
/maintenance add Moderator2

# Verify the whitelist
/maintenance list

​
Temporary Access

Grant temporary access to a builder during maintenance: 
# Add the builder
/maintenance add BuilderName

# When they're done, remove them
/maintenance remove BuilderName

​
Preparing for Maintenance

Before enabling maintenance, ensure all necessary staff are whitelisted: 
# Check current whitelist
/maintenance list

# Add any missing staff
/maintenance add MissingStaff

# Enable maintenance
/maintenance on

​
Troubleshooting

​
Player Cannot Join Despite Being Whitelisted

  1. Verify the player is in the whitelist: /maintenance list
  2. Check the UUID is correct in WhitelistedPlayers.yml
  3. Ensure maintenance is actually enabled: /maintenance status
  4. Reload the plugin: /maintenance reload
  5. Check for permission conflicts (deny permissions may override)

​
UUID Not Found

If adding a player fails with “UUID not found”:
  1. Verify the username is correct (case-sensitive)
  2. Check if the player has changed their username
  3. Try adding by UUID directly
  4. Enable fallback-to-offline-uuid for offline-mode servers

​
Whitelist Not Syncing Across Proxies

  1. Verify Redis is properly configured and connected
  2. Check Redis connection: Look for errors in the console
  3. Ensure all proxies are using the same Redis instance
  4. Try reloading the plugin on all proxies

Build docs developers (and LLMs) love

Get started for freeTalk to us