FAQ & Troubleshooting — Reference

General Questions

What does VoxelBench measure?

VoxelBench measures your Minecraft server's performance through 26 built-in tests covering hardware (disk, memory, network serialization, multi-core CPU), single-core CPU, and gameplay (chunk loading, hoppers, explosions, redstone, entities, lighting, etc.). A full benchmark is combined into a single VoxelScore for easy comparison, and Stress Limit mode finds how much load of each kind your server sustains. See Benchmarks.

Does running a benchmark affect my players?

Yes, temporarily. During gameplay tests, the server lags because VoxelBench intentionally stresses specific systems. We recommend:

Running benchmarks during low-activity periods, ideally with no other players online (the pre-flight checks warn you when there are)
Warning your players beforehand
Running the tests in a dedicated benchmark world (/bench world create, then /bench world set)
Using /bench stop if you need to abort

How long does a full benchmark take?

Typically 10-15 minutes depending on your server's hardware. Multi-run mode multiplies that by the number of runs.

Can I run benchmarks on a production server?

Yes, but keep in mind:

There will be temporary TPS drops during gameplay tests
All test entities and blocks are cleaned up automatically
Outside voxelbench_* worlds, no other entity is removed: your players' animals, villagers and items stay (see Safety Guards)
A cooldown (30 minutes by default) prevents accidental re-runs
Run during off-peak hours for best results

Can I start a benchmark from the console?

No. /bench start, /bench stresslimit, /bench tier and /bench custom run need a connected player, because the tests rely on chunk activation, entity ticking and player state save/restore. Hardware tests and many single tests can be run from the console; see Commands.

What is the screen that opens before my benchmark starts?

The pre-flight check. VoxelBench lists the risks it found (a pinned world that is not flat or not a benchmark world, no pinned world while benchmark.auto-temp-world is off, other players online, server already under load, free hosting, plugins likely to interfere) and lets you start or cancel. See Configuration - Confirmation.

Are my results public?

Not by default. Benchmark and stress limit results are submitted to voxelbench.com, and who can see them depends on whether the server is linked:

from a server that is not linked, the report is anonymous: anyone who has its link can open it, for 30 minutes;
from a linked server, the report goes to your account and stays private until you make it unlisted (anyone who has the link) or public (listed, and eligible for the leaderboard). A custom profile report can never be public.

In both cases, you control the level of hardware information shared via the anonymization setting.

How is the VoxelScore calculated?

The VoxelScore is computed by voxelbench.com from the submitted results, not by the plugin. The plugin displays the total score, a rank and three category sub-scores: Single-Core (40%), Gameplay (40%) and Hardware (20%). Higher scores indicate better server performance.

Troubleshooting

"Rate limit active!" message

A local cooldown (30 minutes by default, rate-limiting.local-cooldown-minutes) exists between benchmark runs. /bench status shows the remaining time. Wait for the cooldown to expire, or use /bench start force with the voxelbench.start.force permission.

Benchmark gets stuck

If a test appears frozen:

Use /bench stop to cancel
Check the server console for error messages
If the test was a gameplay test, verify the test world is loaded (/bench world show)
Try running the specific test individually: /bench test <testName>

"Connection failed" when submitting results

VoxelBench needs to reach voxelbench.com via HTTPS. Run /bench ping: it checks DNS resolution, then the TCP, TLS and HTTP connection, and tells you which step fails. Also check that:

Your server can make outgoing HTTPS connections (port 443)
voxelbench.com is not blocked by a firewall or proxy
You use an official VoxelBench release: the backend refuses reports from builds it does not recognize

Nothing is lost when the submission fails: every run writes its local report when it ends, before anything is sent. A benchmark whose submission failed is kept without a score, with the error, and /bench reports shows it as No score rather than a zero.

GUI not opening

/bench gui only works for a player, not from the console
Ensure you have the voxelbench.gui permission
Check the server console for errors

Tests create blocks/entities that aren't cleaned up

VoxelBench removes what its tests create, even when a test fails or is stopped. If something is left behind:

Check the server console for errors during the test
/bench zones lists the test zones of the last run and names its world. A temporary world is deleted at the end of the run, leftovers included, and /bench zones then says that it no longer exists. In a voxelbench_* world that still exists, /bench zones clean all removes the entities and dropped items around the zones; it removes nothing in any other world, the main world included (clean and tp need the voxelbench.world permission)
Test zones are placed far away in the benchmark world; in a dedicated voxelbench_* world you can simply delete it (/bench world delete)
Report this as a bug

Plugin not loading

Check the Java version: java -version (at least Java 16, and the version your Minecraft version requires; see Compatibility)
Check the server version: must be 1.17 or newer
Check for errors in the console during startup
Ensure the JAR is in the plugins/ folder (not a subfolder)
Verify the JAR is not corrupted (re-download if needed)

Wrong language

VoxelBench auto-detects each player's Minecraft client language. To override:

For one player: /bench lang en_US (and /bench lang auto to go back to detection)
For all players: set language.force: true and language.default: en_US in config, then restart

Monitoring dashboard not accessible

Check the web server is running: /bench monitor web status
Verify the port is correct (default: 8080, or 8443 with HTTPS)
Check the firewall allows incoming connections on the configured port
If accessing remotely, ensure bind-address is 0.0.0.0 (not 127.0.0.1); the dashboard then refuses to start until a password is set (/bench monitor auth password <password>, from the console)
If the IP whitelist is enabled, check your IP is allowed (/bench monitor whitelist list)
Check for port conflicts with other plugins

HTTPS certificate errors

If using a self-signed certificate:

Browsers will show a security warning - this is normal for self-signed certs
You can add an exception in your browser
For production use, consider using a proper SSL certificate

DiscordSRV notifications not working

The current version of VoxelBench reads the DiscordSRV settings but does not post notifications to Discord yet. See Integrations - DiscordSRV.

PlaceholderAPI placeholders not showing

Verify PlaceholderAPI is installed and working
Use /papi parse me %voxelbench_players% to test
TPS and MSPT placeholders return N/A until VoxelBench's tick monitor has been started (web dashboard, push mode, boss bars, remote monitoring or a test)
Score placeholders return N/A until a full benchmark has completed since the last restart

Performance Tips

For better benchmark scores

Reduce other plugins: Disable resource-heavy plugins during benchmarks
Allocate enough RAM: Ensure the JVM has sufficient heap space
Use modern Java: newer Java versions bring garbage collection and JIT improvements
Use Paper: Paper includes many performance optimizations over Spigot
Tune JVM flags: Use optimized startup flags (Aikar's flags recommended)

For more consistent results

Run several benchmarks in a row (/bench start 5, or /bench start warmup 3 to discard a warm-up run) and compare
Ensure the server is idle during benchmarks
Close any running backup tasks
Avoid running during garbage collection storms (increase heap if needed)