Troubleshooting

Troubleshooting

The plugin didn't load / commands don't work at all

Check your console output from the moment the server starts up. If SXBans hits an unexpected error during startup, it disables itself and logs why — search your log for Failed to enable SXBans. The most common causes:

• A malformed config.yml or messages.yml — if you hand-edited either file and broke the YAML syntax (a missing quote, bad indentation), the plugin can't load it. Run the file through any online YAML validator, or just delete it and let the plugin regenerate a fresh one.
• A database connection failure — if database.type is set to mysql or postgresql and the plugin can't reach that server, it'll fail to start. Double-check host/port/credentials.
• A port conflict — if web.port is already in use by something else on the machine, the web server won't bind. Change the port or find what else is using it.

/ban (or another command) seems to be doing something else entirely

If a command name conflicts with another plugin — or with the server software's own built-in fallback commands — whichever one registers last/wins the conflict is the one that responds. Check plugins/ for anything else that might be claiming ban, mute, kick, etc., and check your console for "command conflict" style warnings on startup.

I edited messages.yml and nothing changed

• Make sure you're editing the file inside plugins/SXBans/messages.yml, not a copy somewhere else, and that you saved it.
• Run /sxbans reload (or restart) after editing — changes aren't picked up live.
• Validate the YAML. A broken quote or bad indentation on one line can silently prevent that whole section from loading correctly. An editor with YAML syntax highlighting (VS Code, Notepad++, etc.) will flag most of these instantly.

Hover tooltips aren't showing on broadcast messages

• Confirm the punishment type you're testing actually has a hover: list defined under broadcast: in messages.yml — if it's empty or missing for that specific type, there's nothing to show.
• Make sure you're actually hovering over the broadcast message text itself in chat, not just glancing at it — client-side, hover tooltips only render while your cursor is directly over the message.
• If broadcasts aren't appearing at all for a punishment type, check broadcast_to_everyone and permission for that type — if it's false and you don't hold that permission node, you won't see the broadcast in the first place.

Bans/mutes aren't syncing between servers

See the checklist in Network Setup — it's almost always a mismatched Redis config or a duplicate server-name between two servers.

Unicode / emoji showing as ? or garbled text

• If you're on MySQL, make sure your database and tables are using utf8mb4, not the older 3-byte utf8 charset — the latter can't store emoji at all. See Database Setup.
• If it's specifically your server console showing garbled text rather than in-game chat, that's usually your terminal/console encoding, not the plugin — the actual message sent to players over the network protocol is unaffected either way. On Windows, running your server launch script with a UTF-8 codepage (chcp 65001) generally clears this up.
• Make sure whatever editor you're using to edit messages.yml is saving the file as UTF-8 and not falling back to a legacy Windows codepage.

I lost my web panel admin password

Covered in Web Panel.

The web panel history page is empty / punishments disappear from it

Double-check you're not looking at a filtered/active-only view — expired and removed punishments should still show up under full history, not just the active list. If records are genuinely missing entirely (not just filtered), check your console for storage errors around the time those punishments were issued — a failed write would explain gaps.

Still stuck

Open an issue with:

• Your server software and Minecraft version
• The SXBans version
• Your database.type
• The relevant section of your console log (not just "it doesn't work" — the actual error text)

That's usually enough to spot the problem in a couple of minutes instead of a couple of days of back and forth.