Troubleshooting
The problems server owners actually hit.
On this page
Check the server console first. Each card gives the symptom, the likely cause and the fix.
Startup
Console:
AlphaPractice is disabled — this server is waiting for approval.- Cause
- A new server starts as pending, and the plugin stays off until AlphaStudio approves it.
- Fix
- Send the server id from the next console line to AlphaStudio, then restart once it is approved. See Server approval.
The plugin does not load, and PacketEvents is mentioned
- Cause
- PacketEvents is a hard dependency and is missing, or it is an incompatible build.
- Fix
- Install a compatible PacketEvents as its own plugin. See Install PacketEvents.
Java version error
- Cause
- A 26.x jar needs Java 25, and a 1.21.x jar needs Java 21.
- Fix
- Use the jar that matches your server. See Choose the right jar.
Matches and queues
The queue never finds a match
- Cause
- No enabled arena allows that ladder, the ladder is frozen or disabled, or there are too few players in the queue.
- Fix
- Check
/arena infoand the ladderenabledflag, and that no arena is frozen.
A player cannot join ranked
- Cause
- Their division is below
MIN-DIVISION-FOR-RANKED, their ping is aboveMAX-PING, they used their daily limit, or they were banned from ranked. - Fix
- Check each one. Staff can add to the daily limit and lift a ranked ban from
/practice.
An arena cannot be edited or deleted
- Cause
- It is enabled, or it has copies.
- Fix
- Run
/arena disable <arena>first. See Managing arenas.
Data
Statistics are missing after a crash
- Cause
- Data is written by auto-save every 10 minutes and on shutdown.
- Fix
- Keep
AUTO-SAVE.ENABLEDon, and shortenINTERVALif needed.
The shop is empty
- Cause
menus/shop.ymlships with an emptyITEMSsection.- Fix
- Add items using the example in the file. See The shop.
Before going live
This build has regression tests and a full build check, but live match testing is still advised before production use. Try every ladder you plan to offer with two real accounts.