Skip to main content
The Maintenance plugin can display a custom server icon when maintenance mode is active, making it visually clear that the server is under maintenance.

​
Enabling Custom Icons

Enable the custom icon feature in your config.yml: 
# If set to true, the server icon will be changed to the 'maintenance-icon.png' file in the plugin's folder during maintenance.
custom-maintenance-icon: false
Set this to true to enable the custom icon feature.

​
Icon File Location

The plugin looks for a file named maintenance-icon.png in the plugin’s data folder:
  • Paper/Spigot: plugins/Maintenance/maintenance-icon.png
  • BungeeCord: plugins/Maintenance/maintenance-icon.png
  • Velocity: plugins/maintenance/maintenance-icon.png
  • Sponge: config/maintenance/maintenance-icon.png
1

Create your icon

Design a 64x64 PNG image for your maintenance icon. This could include text like “Maintenance”, a warning symbol, or any custom design.
2

Save as maintenance-icon.png

Name the file exactly maintenance-icon.png (case-sensitive on Linux).
3

Place in plugin folder

Copy the file to your plugin’s data folder (see locations above).
4

Enable in config

Set custom-maintenance-icon: true in your config.yml.
5

Reload or restart

Run /maintenance reload or restart your server to apply the changes.

​
Icon Requirements

Your server icon must meet these specifications:

​
Image Format

  • Format: PNG (Portable Network Graphics)
  • File extension: .png
  • Color depth: 24-bit RGB or 32-bit RGBA

​
Dimensions

  • Width: 64 pixels
  • Height: 64 pixels
  • Aspect ratio: 1:1 (square)
Icons that don’t match the exact 64x64 pixel dimensions may not display correctly in the Minecraft client. Always verify your icon size before uploading.

​
File Size

  • Recommended: Under 20 KB
  • Maximum: No hard limit, but larger files increase network overhead
The Minecraft protocol encodes the icon as Base64, so extremely large files (>100 KB) may cause performance issues during server pings.

​
Icon Design Tips

​
Use Clear Imagery

The icon is displayed at only 64x64 pixels, so use simple, bold designs that are easy to recognize:
  • Large text (avoid small fonts)
  • High contrast colors
  • Simple shapes and symbols
  • Minimal detail

​
Common Design Ideas

  • ⚠️ Warning/caution symbol
  • 🔧 Wrench or tools for “under construction”
  • 🚧 Construction barrier
  • 🔴 Red circle with “Maintenance” text
  • 🛠️ Hammer and wrench crossed

​
Transparency Support

PNG alpha transparency is fully supported. You can create icons with:
  • Rounded corners
  • Soft shadows
  • Irregular shapes
  • Partial transparency effects

​
Testing Your Icon

  1. Enable maintenance mode: 
    /maintenance on
  2. Refresh your server list (or remove and re-add the server)
  3. Check the icon - It should display your custom maintenance icon
  4. Disable maintenance mode: 
    /maintenance off
  5. Verify the icon returns to normal when maintenance is disabled

​
Troubleshooting

​
Icon Not Displaying

Check the file name: 
# The file must be named exactly:
maintenance-icon.png
Verify the file location: 
# Make sure the file is in the correct directory
ls plugins/Maintenance/maintenance-icon.png
Check config setting: 
custom-maintenance-icon: true  # Must be true
Reload the plugin: 
/maintenance reload

​
Icon Appears Corrupted

  • Verify the image is exactly 64x64 pixels
  • Ensure the file is a valid PNG format
  • Try re-saving the image with a different tool
  • Check that the file isn’t corrupted

​
Icon Doesn’t Change Back

  • Disable maintenance mode: /maintenance off
  • Reload the plugin: /maintenance reload
  • Restart the server if issues persist
  • Check that your server’s default icon (server-icon.png) exists

​
Platform-Specific Notes

​
BungeeCord/Velocity

On proxy servers, the maintenance icon is applied to the proxy’s server list ping response. All backend servers will show the same maintenance icon when the proxy is in maintenance mode.

​
Spigot/Paper

The icon loads when the plugin initializes. If you change the icon file, reload the plugin to apply the new icon.

​
Sponge

The icon path follows Sponge’s config directory structure (config/maintenance/ instead of plugins/Maintenance/).

​
Example Workflow

# 1. Stop the server (optional, can do while running)
# 2. Create and upload your maintenance-icon.png
scp maintenance-icon.png user@server:/path/to/plugins/Maintenance/

# 3. Enable the feature in config.yml
custom-maintenance-icon: true

# 4. Reload the plugin
/maintenance reload

# 5. Enable maintenance to test
/maintenance on

# 6. Check your server list to see the custom icon

Build docs developers (and LLMs) love

Get started for freeTalk to us