Skip to main content

Troubleshooting

Plugin Fails to Load​

Symptom: No HopperLimiter output in console.

Checklist:

  • Java 17+ installed (java -version)
  • Paper or Spigot 1.20+ server
  • JAR not corrupted — re-download if needed

Hoppers Still Being Placed Above Limit​

Symptom: Players can place more hoppers than the configured cap.

Steps:

  1. Run /hl reload to ensure config changes are loaded
  2. Confirm counting-mode matches the limits you set (e.g. COMBINED needs combined-limit, not separate limits)
  3. Check if the player has hopperlimiter.bypass — they would be exempt
  4. Verify the chunk is actually at the limit with a manual count

Hoppers Being Removed Unexpectedly​

Symptom: Players report hoppers disappearing.

Cause: The periodic validator found hoppers above the limit and applied the overflow-action.

Fix options:

  • Raise the limit: combined-limit: 64
  • Switch overflow-action: BREAK so items are dropped rather than vanishing
  • Grant bypass to affected players if they have a legitimate reason

Block Placement Message Not Showing​

Symptom: Players are silently blocked with no feedback.

Fix: Check messages.placement-blocked in config.yml — ensure it is not empty and contains the correct placeholders ({limit}, {current}).

/hl reload Says "Unknown Command"​

Symptom: The reload sub-command isn't recognized.

Fix: Ensure you are using the correct alias. Try /hopperlimiter reload or /hopperlimit reload. The command only reloads configuration — it does not change already-cached chunk counts.

Hopper Minecart Count Not Tracked​

Symptom: Hopper minecarts are placed freely without limit enforcement.

Fix: In COMBINED mode, both types share the same counter. In SEPARATE mode, ensure hopper-minecarts-limit is set. In WEIGHTED mode, ensure hopper-minecart-weight > 0.

High CPU During Validation​

Symptom: TPS drops at regular intervals (matching validation-interval).

Fix: Lower chunks-per-tick (e.g. from 10 to 3) and/or increase validation-interval (e.g. from 30 to 120 seconds). This spreads the scan work over more ticks.