Skip to main content

Troubleshooting

Plugin Fails to Load​

Symptom: No HomesGUI-Addon output in console.

Checklist:

  • Java 17+ installed
  • Paper or Spigot 1.20+
  • Advanced Teleport is installed and loads successfully before this addon

"Advanced Teleport not found" Warning​

Symptom: Console shows the addon loaded but AT integration is disabled.

Fix:

  1. Confirm AdvancedTeleport.jar is in plugins/
  2. Check AT loads without errors before this addon (check load order)
  3. The addon uses a soft dependency — it will load but home commands won't work until AT is present

GUI Shows No Homes​

Symptom: The GUI opens but is empty, even though homes are set in AT.

Steps:

  1. Confirm homes exist: use AT's native /homes command
  2. Check the player has at.member.homes permission
  3. Run /homesguireload to refresh config
  4. Restart the server if the AT API hook failed silently on load

Left-Click Does Not Teleport​

Symptom: Clicking a home in the GUI has no effect.

Fix:

  1. The player may be on cooldown — check AT's cooldown settings
  2. AT warmup may be running — the player needs to stand still
  3. The home may be in a disabled world — check AT's world restrictions
  4. Confirm at.member.homes is granted

Custom Icons Not Saving​

Symptom: Custom icons reset after rejoining.

Fix:

  1. Confirm custom-icons.enabled: true
  2. Check file permissions on plugins/HomesGUI-Addon/home-icons.yml
  3. Ensure the plugin has write access to its data folder

GUI Layout Looks Wrong​

Symptom: Items are in odd positions or border is missing.

Fix:

  1. Run /homesguireload after config changes
  2. Verify show-borders: true/false is set correctly
  3. Check that button slot numbers (49, 48, 50) don't conflict with each other

/homesgui Says "Unknown Command"​

Symptom: The command is not recognized.

Fix:

  1. Try the aliases: /hgui or /homesmenu
  2. A server restart is required after changing the command name or aliases in config
  3. Confirm the addon loaded — check console for any load errors

Teleport Ignores AT Warmup​

Symptom: Players teleport instantly, bypassing the AT warmup.

Note: The addon calls the AT API for teleportation. If warmup is not triggering, the issue is in AT's configuration, not the addon. Check AT's config.yml for warmup settings.