Skip to main content

Players cannot be routed anywhere

No live owner for that region. Check /shard topology on any shard: a dash means the row is missing or stale. Either the shard is down, or it is up and cannot reach MongoDB to announce itself.
Each shard needs shard.address, the host and port the proxy dials. Without it the shard announces no address and the proxy leaves it to velocity.toml. Look for registered shard on the proxy at startup.If you are declaring servers by hand instead, the name in velocity.toml must match the name the shard announces exactly.
The grid disagrees somewhere. Compare region-size, regions-x and regions-z on every shard and the proxy. /shard info prints the grid it is using.

Crossings

Transfers are timing out. Usually Redis: the offer never reaches the neighbour, so the handoff is reverted and the player is nudged back. /shard info reports Redis as up or DOWN.
The client did not keep its world. By far the most common reason is the proxy: plain Velocity, or atlas-proxy with remove-reconfig or keep-client-world-on-switch off. The proxy console says so when the Atlas plugin starts, and each shard logs this geo's proxies do not all keep the client's world — turn both settings on and run /velocity reload.Otherwise the entity id could not be reused, which is logged at arrival, or the player is crossing between geos, where the fallback is a genuine reconnect.An id outside the reserved range — usually from a respawn on an old record — is migrated on the player’s next plain login, where there is no world to keep.
Turn on tuning.arrival-trace with a value like 16 and cross again. It logs each movement report with its step size; anything larger than a client can walk is the server or the proxy overruling it, and the timestamp says which part of the arrival did it.Turn it off afterwards. It is sixteen log lines per crossing per player.
The lease renewal failed, so this shard stopped being the owner and refused to keep writing. Reconnecting is correct and lands the player on whoever owns them now. If it happens in bursts, MongoDB is unreachable or slow enough that renewals are missing their window.

Borders look wrong

The two sides are not sharing their border. Check, in order: tuning.border-chunks is on for both shards; both use the same level-seed; and /shard mirror on the shard showing the wrong terrain. not yet upstream means the owner has never generated that stretch — run /shard pregen there. too late means the chunk was already in memory when it arrived and will be picked up on a later visit. REFUSED FROM NEWER BUILD means the shards run different server builds.If you copied one world folder to every shard instead, the copies have drifted: they must come from the same pre-generated folder.
Check /shard mirror. It counts what was sent, what was applied, and where deltas were dropped: out of band, in unloaded chunks, or unparseable. A rising dropped bad data means the two sides are on different server versions.
A shard with no players on it is deliberately not mirrored to. If somebody is there and it is still empty, check /shard ghosts on the shard that should be receiving, and look for the cap warning on the sender.
A leftover puppet. They are swept as chunks load and when the crossing that created them ends. One that survives means the bookkeeping was lost, usually a plugin reload mid-crossing.

The world is emptying

If entities are disappearing, look for a warning about removing entities at positions outside the configured grid. Nobody owns those coordinates, so anything that wanders there is removed — and if the grid numbers are wrong, most of the world is outside it.

Things that are working as intended