| Wrong GUI is shown | Use mode: AUTO under gui: and leave use-viaversion: true under gui: enabled when ViaVersion is installed. |
| Bedrock players get the dialog menu | Check bedrock-chest: true under gui: and that Floodgate or Geyser is installed on the backend server. |
| Import finds no homes | /homes import essentials reads plugins/Essentials/userdata on the server where you run it. Copy that folder over first if EssentialsX was on another server. |
| Pink / missing sprite icons | Run /homes icontest or /homes icontest <item>, then adjust atlas: "auto" under icons: (inside gui:) or sprite settings. GLYPH/NONE are fallback options. |
| Cross-server home does not connect | Confirm the Velocity companion is installed, server-name matches the proxy config and shared storage is working. |
| Cross-proxy home fails | Confirm Redis is enabled and proxy public host/port values are reachable by clients. |
| Player cannot create more homes | Check default-limit: 3 under homes:, max: 20 under homes: and the highest homes.limit.<number> permission the player has. |
| Player lands next to the home, or gets "isn't safe" | The home's spot is in the air, inside blocks or in lava. safe-teleport under teleport: moves the player to the nearest safe spot or cancels. Set it to OFF to always use the exact spot. |
| Teleport cancels | Review cancel-on-move: true, cancel-on-damage: true and move-threshold: 0.3 under teleport:. |