# VelocityFailover<\/p>\n
A lightweight Velocity proxy plugin that automatically handles server crashes and restarts \u2014 no player left behind.<\/p>\n
## What does it do?<\/p>\n
When a backend server goes down (crash, restart, `\/stop`), VelocityFailover:<\/p>\n
1. **Instantly detects** the server is down
\n2. **Moves affected players** to a limbo server
\n3. **Monitors** the downed server for recovery
\n4. **Automatically reconnects** players back to their original server once it’s ready
\n5. **Blocks** other players from joining unavailable servers with a friendly message<\/p>\n
All of this happens seamlessly \u2014 players see a short message, wait on limbo, and get moved back automatically.<\/p>\n
## Why VelocityFailover?<\/p>\n
– **Zero external dependencies** \u2014 only the Velocity API, nothing else
\n– **Extremely lightweight** \u2014 no constant heartbeat pinging all servers. Recovery pings run *only* on servers that are actually down
\n– **Instant detection** \u2014 uses Velocity’s kick events instead of slow polling intervals. Players are redirected in milliseconds, not seconds
\n– **Gradual reconnection** \u2014 players are transferred back one at a time to avoid overloading a freshly started server
\n– **Smart kick detection** \u2014 distinguishes between server crashes and normal kicks (bans, anticheat, etc.). A banned player won’t end up on limbo
\n– **Connection blocking** \u2014 players trying to manually join a recovering server get a message instead of being thrown into limbo
\n– **No Paper plugin needed** \u2014 runs entirely on the Velocity proxy side<\/p>\n
## Requirements<\/p>\n
– Velocity 3.4.0+
\n– Java 17+
\n– A limbo server registered in `velocity.toml` (e.g. PicoLimbo or an empty Paper server)<\/p>\n
## Installation<\/p>\n
1. Download the latest `.jar` from [Releases](..\/..\/releases)
\n2. Place it in your Velocity `plugins\/` folder
\n3. Start the proxy \u2014 a default `config.yml` will be generated in `plugins\/velocityfailover\/`
\n4. Edit `config.yml` to match your server setup
\n5. Restart the proxy or use \/failoverreload<\/p>\n
## Commands and permissions
\n\/failoverreload – reloads config (permission: velocityfailover.reload) <\/p>\n
## Configuration<\/p>\n
“`yaml
\n# Name of the limbo server registered in velocity.toml
\nlimbo-server: “limbo”<\/p>\n
# Server groups to monitor.
\n# Groups are for organization only \u2014 each server is tracked individually.
\ngroups:
\n lobby:
\n servers:
\n – “lobby1”
\n – “lobby2”
\n spawn:
\n servers:
\n – “spawn1”
\n – “spawn2”<\/p>\n
# Recovery monitor settings
\nrecovery:
\n ping-interval-ms: 2000 # How often to ping downed servers
\n pings-to-ready: 3 # Successful pings in a row before recovery starts
\n grace-period-ms: 5000 # Extra wait after pings pass (lets plugins load)
\n transfer-interval-ms: 50 # Delay between each player transfer
\n ping-timeout-ms: 2000 # Timeout for a single ping<\/p>\n
# Kick reasons that indicate a server shutdown (checked via String.contains)
\n# If a player is kicked with one of these reasons, the server will be marked as offline
\nshutdown-keywords:
\n – “Server closed”
\n – “Server shutting down”<\/p>\n
# Messages sent to players (MiniMessage format) ### Important notes<\/p>\n – The **limbo server must not be listed** in any monitored group \u2014 it is always treated as available ## How it works<\/p>\n “` ## FAQ<\/p>\n **Q: What if a player disconnects while waiting on limbo?** **Q: What if the server crashes again during player transfers?** **Q: Does this replace my hub plugin?** A lightweight Velocity proxy plugin that automatically handles server crashes and restarts \u2014 no player left behind.<\/p>\n","protected":false},"featured_media":165595,"template":"","meta":{"_minecraft_slug":"velocityfailover","_minecraft_project_id":"zLB8BIPd","_minecraft_author":"blixy77","_minecraft_license":"MIT","_minecraft_downloads":21,"_minecraft_follows":1,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"velocityfailover.zip","_minecraft_size_bytes":74900,"_minecraft_version_count":3,"_minecraft_updated_at":"2026-05-15T22:27:53.779930Z","_minecraft_date_created":"2026-04-03T22:37:21.372099Z","_minecraft_date_modified":"2026-04-04T22:30:12.082037Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/velocityfailover","_minecraft_icon_attachment_id":165595,"_minecraft_imported_at":"2026-06-09T17:54:03+00:00","_minecraft_import_hash":"ff7a29bde5384e9f4dfc89aee75cbe4a","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[126,123,869,92,985],"mod_loader":[986],"minecraft_version":[54,55,56,57,58,59,36,60,93,94,101,102,62,37,40,41,73,74,38,78,79,80,81,82,83,167],"class_list":["post-165594","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-management","mod_category-technology","mod_category-transportation","mod_category-utility","mod_category-velocity","mod_loader-velocity","minecraft_version-1-19","minecraft_version-1-19-1","minecraft_version-1-19-2","minecraft_version-1-19-3","minecraft_version-1-19-4","minecraft_version-1-20","minecraft_version-1-20-1","minecraft_version-1-20-2","minecraft_version-1-20-3","minecraft_version-1-20-4","minecraft_version-1-20-5","minecraft_version-1-20-6","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9","minecraft_version-26-1","minecraft_version-26-1-1"],"yoast_head":"\n
\nmessages:
\n sent-to-limbo: “
\n reconnecting: “
\n connection-blocked: “
\n“`<\/p>\n
\n– Server names in the config must match exactly what is in your `velocity.toml`
\n– Messages support MiniMessage formatting<\/p>\n
\nPlayer on spawn2 \u2500\u2500> spawn2 crashes
\n \u2502
\n KickListener catches the crash kick
\n \u2502
\n Player redirected to limbo instantly
\n \u2502
\n RecoveryMonitor starts pinging spawn2
\n \u2502
\n 3 successful pings \u2500\u2500> 5s grace period
\n \u2502
\n Players transferred back one by one
\n \u2502
\n spawn2 marked as ONLINE again
\n“`<\/p>\n
\nThey are removed from the reconnect queue. When they rejoin, your existing routing plugin handles them normally.<\/p>\n
\nThe plugin handles this gracefully. Already-transferred players get kicked back to limbo. Remaining players stay on limbo. Recovery restarts from scratch.<\/p>\n
\nNo. This only handles crashes\/restarts.<\/p>\n","protected":false},"excerpt":{"rendered":"