Troubleshooting

Three commands answer most questions:

/blazebans version
/blazebans permissions
/blazebans dump

version reports the running version, the platform it detected, and the storage backend actually in use. If the storage line is not what you configured, that is your problem.

permissions lists every node and confirms your account is recognised as an administrator.

dump writes a diagnostic file to plugins/BlazeBans/dumps/ with version, platform, storage, JVM arguments, and loaded configuration, with passwords, tokens, and webhook URLs stripped out. It is safe to share.

Check the Java version. BlazeBans needs Java 21 or newer. java -version on the machine running the server.

Check the server version. Paper 1.21 or newer, a Folia build, or Velocity.

Check the console for a download failure. On Paper and Folia, BlazeBans fetches its supporting libraries on first start. A host that blocks outbound connections stops that, and the plugin cannot start without them. Allow repo.papermc.io and Maven Central, then start again. This does not apply on Velocity, where those libraries ship inside the jar.

Read the whole error. The first line names what failed. An error about a missing class is almost always the download above not having completed.

Not found. Either the plugin did not enable, or the command was renamed under commands.names in settings.yml. Check the console for the enable line, and check /blazebans version works.

Found but refused. A permission is missing. Nothing defaults to true except the two lockdown bypass nodes. Check with your permission plugin:

# /lp user <player> permission check blazebans.command.ban

Renamed and still not working. Command names register at startup. Reloading does not re-register them; restart the server.

The refusal message names the check that failed.

The quickest diagnostic is to run the same command from console. Console bypasses every check except exempt.players, so:

• Works from console: it is one of hierarchy, exemption, duration, or scope.
• Refused from console too: the target is in exempt.players.

See Hierarchy and exemptions.

Check /blazebans version. If storage says SQLite when you configured MySQL, the emergency fallback is active.

BlazeBans falls back to SQLite when the configured backend is unreachable at startup, rather than failing to load. It warns administrators in game and in console.

That keeps moderation working, but punishments issued during the fallback go to the local file, not your real database. They will not be there when the connection returns.

Fix the connection. Check host, port, database, username, and password in database.yml. Confirm the database accepts connections from this machine and that the user has rights on the database.

Then restart and check whether anything was issued during the outage.

Check the scope. /history <player> shows which server each record belongs to. A record scoped to another server is stored, visible, and not enforced here. See Servers and scope.

Check it is still active. The history entry shows status. An expired or revoked record does nothing.

Check for a bypass. blazebans.bypass.ban on the target prevents it.

On a network, check the database. If servers do not share one, each has its own history. SQLite cannot be shared.

Chat is blocked but private messages are not. The command is not in muted-commands.blocked. Add it, plus every alias and the namespaced form.

Voice chat still works. A text mute does not cover voice without the voice chat addon and auto-voice-mute-regular-mutes: true.

Staff can still talk while muted. They hold blazebans.mute.commands.bypass or blazebans.bypass.mute.

See Mute enforcement.

Did you reload? /blazebans reload after every change.

Was it refused? A YAML error means the previous configuration stays active. The error names the file, the line, and what was expected.

Was it a command name? Those need a restart.

Message files use a colon. /blazebans reload messages:en_us.yml, not a slash.

Check the reload report. It names each file, line, key, and the old and new value. If your key is not listed, the value you edited was not the one being read.

The usual YAML mistakes

Unquoted hex. positive: #ff650d is a comment. It has to be "#ff650d".

Tabs. YAML needs spaces. An editor that inserts tabs will break every file it touches.

Inconsistent indentation. Two spaces per level, uniformly.

Unquoted special values. Anything containing :, #, or a leading zero needs quotes.

Rendering as literal text. PlaceholderAPI is not installed, or BlazeBans started before it. Check /papi list for blazebans.

Rendering blank. No value is available and placeholder-api.values.none is an empty string. That is configured behaviour, not a fault.

Out of date. Values refresh every five seconds. Wait, then check again.

Voice mute placeholders always false. The voice chat addon is not installed, so no voice mute records exist.

See PlaceholderAPI.

Check the switches. enabled: true in discord.yml, the relevant event under events, and the punishment type under punishment-types. All three have to allow it.

Check the URL. It should be the full webhook URL from Discord's channel settings.

Check for --silent. Silent punishments do not post.

Check the console. Failed webhook calls are logged with a reason.

See Discord webhooks.

Check the permission. blazebans.command.editor.

Check outbound HTTPS. The server needs to reach blazestudios.store. A strict egress firewall blocks the editor while everything else keeps working.

Check the link has not expired. Sessions last 24 hours. Run /blazebans editor again for a new one.

Verification is refused by name. The session belongs to whoever opened it. That staff member has to verify it, or they need their own link.

See Web editor.

File lock error. The source plugin is still running. Stop it, or the whole server, and try again.

Connection error. Check the credentials in import.yml and that the database is reachable from this machine.

Ambiguous match on LiteBans. More than one table matches the expected pattern. Set table-prefix to LiteBans' own sql.table_prefix.

Everything skipped. BlazeBans connected but found nothing convertible. Confirm you pointed it at the right database.

Re-running an import is safe. Duplicates are detected rather than doubled.

See Importing punishments.

A regex is matching more than you intended.

Comment out your patterns one at a time and reload until it stops. The last one you removed is the problem.

Remember YAML needs backslashes doubled: \b is written \\b.

While tuning, set mute-duration short. A one-hour mute is cheap to apologise for. See AutoMod.

BlazeBans keeps database work away from the part of the server that ticks the game, so it should not cost you frames. If your server is lagging and BlazeBans is being blamed, check these three before anything else:

A slow database. A remote MySQL server on a poor connection makes every lookup slow, and lookups are most of what BlazeBans does. Check how long a round trip between the game server and the database actually takes. Moving the database closer, or back to SQLite on a single server, is usually the whole fix.

Placeholders. These are almost never the cause. Rendering one never queries the database. If a report points at placeholders, it is measuring the plugin that displays them rather than BlazeBans.

Console commands on templates. A template with console-commands runs those commands right after the punishment, and BlazeBans has no control over how heavy they are. A world rollback command there will be felt. Move anything slow out of the template.

The BlazeStudios Discord.

Bring:

1. The output of /blazebans dump.
2. What you expected to happen.
3. What actually happened, with the exact message.
4. What you have already tried.

The dump answers most of the first round of questions on its own. It contains no passwords, tokens, or webhook URLs, so it is safe to attach.