> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.mrerrorx.dev/primaxbattleroyalex/llms.txt
> Use this file to discover all available pages before exploring further.

# PrimaxBattleRoyaleX Common Issues: Troubleshooting Guide

> Fix common PrimaxBattleRoyaleX issues: plugin not loading, worlds not deleting, squad teams not working, and PlaceholderAPI placeholders not showing.

<Warning>
  **Server requirements:** PrimaxBattleRoyaleX generates a fresh world for every match and deletes it once the match ends. World generation runs on the server's main thread, so a weak CPU or low RAM will cause noticeable lag. A quality managed Minecraft host or a dedicated VPS with a strong single-thread CPU and ample RAM is strongly recommended. Shared or budget hosting is not suitable.
</Warning>

This page covers the most common issues server administrators encounter with PrimaxBattleRoyaleX and how to resolve them. Work through the relevant accordion below to diagnose and fix your problem.

<AccordionGroup>
  <Accordion title="Plugin won't load / not appearing in /plugins">
    * **Check BetterTeams is installed** — BetterTeams is a required dependency. Without it, PrimaxBattleRoyaleX will refuse to enable.
    * **Verify your server is running Paper 1.21+** — Spigot and CraftBukkit are not supported. Download Paper from [papermc.io](https://papermc.io).
    * **Check the server console for error messages** during startup — errors printed at boot will tell you exactly what went wrong.
    * **Common error:** `Cannot find required dependency BetterTeams` — install the BetterTeams plugin and restart your server.
  </Accordion>

  <Accordion title="Match worlds not being deleted after a match">
    * **Ensure no players are still inside the world** — all players must return to the lobby before the world can be unloaded and deleted.
    * **Check your server's file permissions on the worlds folder** — the server process must have write access to delete world directories.
    * **World deletion has a 5-second cleanup delay** after match end — wait a moment before assuming deletion has failed.
    * **Check the console for file permission errors** — any deletion failures will be logged with details.
  </Accordion>

  <Accordion title="Squad mode / teams not working">
    * **Verify BetterTeams is installed and up to date** — squad mode depends on BetterTeams for team management. Outdated versions may cause integration issues.
    * **Check squad configuration in `game-settings.yml`** — review the `min-team-size` and `min-teams` values to ensure they match your intended setup.
    * **The team leader must be in the lobby when queuing** — leaders queuing from outside the lobby will not be able to start the team queue.
    * **If using auto-team creation**, ensure it is enabled in your settings — it may be disabled by default.
  </Accordion>

  <Accordion title="Placeholders showing as literal text (e.g., %primaxbr_kills%)">
    * **Run `/plugins`** and confirm PlaceholderAPI appears in the list highlighted in green (enabled).
    * **Run `/papi list`** and look for `primaxbr` in the output — this confirms the expansion is registered.
    * **Test a placeholder directly:** `/papi parse me %primaxbr_kills%` — this should return a number, not the raw placeholder string.
    * **If `primaxbr` is missing from `/papi list`**, try `/papi reload` to force the expansion to re-register.
  </Accordion>

  <Accordion title="All PlaceholderAPI placeholders return 0">
    * **Player data may not be loaded yet** — try having the affected player disconnect and reconnect to the server.
    * **Verify `plugins/PrimaxBattleRoyaleX/data.yml` exists** — if the file is missing, player statistics have not been saved or were accidentally deleted.
    * **Check the server console for errors during plugin startup** — data loading failures are logged at boot and will explain why stats are unavailable.
  </Accordion>

  <Accordion title="PlaceholderAPI expansion not registering">
    * **PlaceholderAPI MUST load before PrimaxBattleRoyaleX** — if PlaceholderAPI loads after PrimaxBattleRoyaleX, the expansion registration will be skipped. Check your plugin load order.
    * **Check the console for the confirmation message:** `✓ PlaceholderAPI expansion registered` — if this line is absent, registration did not occur.
    * **Try `/papi reload`** to force PlaceholderAPI to re-scan and register expansions without restarting the server.
  </Accordion>

  <Accordion title="Players teleport to wrong location after a match">
    * **Re-set your lobby and spawn locations** using `/brsetlobby` and `/brsetspawn` — run each command while standing at the exact position you want players sent to.
    * **Ensure you ran the commands from the correct positions** — locations are saved from wherever you are standing when the command is executed.
    * **Check `config.yml`** for the stored lobby and spawn coordinates to confirm they point to the expected positions.
  </Accordion>
</AccordionGroup>

<Info>
  For issues not covered here, check the server console for error messages and report them on [GitHub Issues](https://github.com) with your full console output so the issue can be diagnosed accurately.
</Info>