Troubleshooting
Plugin won’t load
| Symptom | Fix |
|---|---|
| “Unsupported Java version” | Upgrade to Java 21+ — see Requirements |
| “Error loading plugin” in console | Remove duplicate PEX jars from plugins/ |
Plugin missing from /plugins |
Check the jar is named PermissionsExPlus-*.jar and not corrupted |
Commands don’t work
| Symptom | Fix |
|---|---|
| “Unknown command” | PEX not loaded — check console for errors on startup |
| “You don’t have permission” | Grant yourself access: /pex group admin add permissions.* (from console) |
| Changes not visible | Run /pex reload after manual file edits |
Run from console (bypasses permission checks):
pex group admin add permissions.*
pex user YourName group set admin
Player has wrong permissions
Step 1 — Check what PEX thinks:
/pex user Steve check essentials.fly
/pex user Steve list
/pex user Steve group list
/pex hierarchy
Step 2 — Common causes:
| Cause | Fix |
|---|---|
| Player not in any group | /pex user Steve group set default |
| Permission on wrong world | Add world: /pex user Steve check essentials.fly world_nether |
| Negation overrides grant | Look for -node in /pex user Steve list |
| Another plugin overriding | Check if LuckPerms or another perm plugin is also installed |
| Stale superperms cache | /pex reload or restart server |
Step 3 — Debug logging:
/pex toggle debug
/pex user Steve toggle debug
Watch the console while the player triggers the permission check.
Prefix not showing in chat
| Cause | Fix |
|---|---|
| Chat plugin not reading Vault/PEX | Ensure chat plugin supports Vault or PEX directly |
| Wrong group weight | Set higher weight on the group whose prefix should show |
| No prefix set | /pex group admin prefix &c[Admin] |
| Colour codes wrong | Use & not § in commands |
/pex group admin weight 100
/pex group admin prefix &c[Admin]
/pex user Steve group list
Data not saving
| Cause | Fix |
|---|---|
| File permissions | Check server can write to plugins/PermissionsEx/ |
| SQL connection failed | Check database credentials in config.yml |
| Wrong backend active | /pex backend — should show file or your SQL alias |
/pex backend
/pex config permissions.backend
/pex reload
Migration issues
See Migration FAQ.
After importing from another plugin, verify:
/pex groups list
/pex users list
/pex hierarchy
/pex convert uuid
Generate a report
/pex report
Include this output when opening a GitHub issue.
Still stuck?
- Check GitHub Issues for known problems
- Search for your Minecraft + PEX version combination
- Open a new issue with
/pex reportoutput, server type, and Java version