Troubleshooting Guide

The plugin is not optimizing anything

• Run /auroraoptimizer status — confirm the mode is ACTIVE, not PASSIVE, MANUAL or DISABLED
• Verify that thresholds in config.yml are appropriate for the server's actual entity and chunk counts — demo values are too low
• Check that TPS is actually below the configured thresholds; if TPS is 19.5 and the threshold is 17.0, no action is justified
• Run /auroraoptimizer simulate <player> to confirm sub-engines are generating proposals
• Run /auroraoptimizer policy review to verify policies are loaded with the correct parameters

TPS does not improve even though the plugin is active

• Run /auroraoptimizer scan — verify the system is targeting actual hotspot chunks and not adjacent ones
• Check /auroraoptimizer history — confirm actions are reaching SUCCESS status and not REJECTED or ERROR
• If actions succeed but TPS doesn't improve, the root cause may be outside AuroraOptimizer's scope (e.g. tick overhead from other plugins)
• Increase aggressiveness: /auroraoptimizer profile set aggressive
• Run /auroraoptimizer dump and review effectiveness records to identify which action types have low TPS delta

A player complains of reduced view distance

• Run /auroraoptimizer viewdist status <player> to identify which priority level set the current VD
• If the source is an automatic policy: auto-revert will restore it when conditions recover — inform the player and monitor
• For immediate relief: /auroraoptimizer viewdist set player <n> <distance> (P8 override)
• For permanent exemption: grant auroraoptimizer.immune or raise the .viewdistance.max.* cap for their group

Auto-revert is not restoring configuration

• Confirm auto-revert.enabled: true is in config.yml
• Verify that min-uptime-before-revert-ms has elapsed — the default minimum is 2–3 minutes
• Check that recovery thresholds are not configured unrealistically for the server's normal TPS range
• Run /auroraoptimizer history and identify revert events — do they appear as NO_OP or REJECTED?

Console errors during startup

Error Message	Cause	Solution
"ProtocolLib not found"	ProtocolLib absent or failed to load	Install ProtocolLib 5.3.0+; verify clean startup
"Failed to load policies.hopl"	YAML syntax error in .hopl file	Run /auroraoptimizer policy test; fix the reported line
"Java version not supported"	JRE version below Java 21	Upgrade JRE/JDK to Java 21
"API version mismatch"	Paper or Folia below 1.21.11	Upgrade server software
"Sub-engine failed to init"	Sub-engine initialization error	Check console for sub-engine name and stack trace