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:

​
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:
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:
Permission: maintenance.remove

​
List Whitelisted Players

View all whitelisted players:
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:
​
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).

​
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:
Offline UUIDs are generated differently than online UUIDs. A player will have different UUIDs in online vs offline mode.

​
Permissions

Whitelist-related permissions:

​
Bypass Permission

Instead of adding players to the whitelist, you can grant the maintenance.bypass permission:
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

​
Temporary Access

Grant temporary access to a builder during maintenance:

​
Preparing for Maintenance

Before enabling maintenance, ensure all necessary staff are whitelisted:

​
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