Skip to content

Troubleshooting.md

Jump to bottom
Fragmer2 edited this page Apr 8, 2026 · 5 revisions

Troubleshooting

Plugin Not Loading

Check Java version — must be 17 or newer:

java -version

Error UnsupportedClassVersionError → upgrade Java. Download from Adoptium.

Check server software — Vanilla does not support plugins. Use Spigot, Paper, or Purpur.

Corrupted JAR — if file is 0 KB or download was interrupted, delete and re-download.

Linux permissions:

chmod 644 plugins/SpawnChestPlugin*.jar
chmod 755 plugins/SpawnChestPlugin/

Chests Not Spawning

Run these in order:

/nextchest          # is the timer still counting?
/chestnow           # force spawn — does it work?
/testchestzone      # do the sample coordinates look valid?
/chestconfig get settings.enabled-worlds

World not in list — add it:

/chestconfig set settings.enabled-worlds [world,your_world]

No valid location found — spawn zone may be too small or all surfaces excluded:

settings:
  spawn-zone:
    min-distance: 200
    max-distance: 5000
    exclude-surfaces:
      water: true
      lava:  true

YAML error — malformed config prevents loading. Validate at yamllint.com, fix the reported line, then /reloadchestconfig.

Common YAML mistakes:

# Wrong — tab indentation
	spawn-interval-seconds: 600

Wrong — missing space after colon


enabled:true


Correct


enabled: true
spawn-interval-seconds: 600

Batch Spawn (3 chests configured, fewer spawn)

Check chest-count-per-interval:

/chestconfig get settings.chest-count-per-interval

If the second or third chest shows "Spawn in progress" warning in console, the batch queue is competing with itself. This is fixed in 4.4 — update if using an older version.

Legendary Items Not Working

/chestconfig get legendary-items.enabled
/chestconfig get legendary-items.<item>.enabled
/cooldowns
/chestconfig get abilities.pvp-protection

If pvp-protection: true, abilities do not trigger against other players — this is intentional.

Phoenix Feather not resurrecting — must be in inventory when death occurs. Killed by /kill is not protected.

Master Pickaxe not smelting — works on Iron, Gold, Copper, Ancient Debris only. Diamond/Emerald/Coal drop normally.

Void Shovel not digging 3×3 — must hold Shift while breaking a diggable block.

Guardian Bow not homing — targets must be within homing-range blocks of the arrow, and homing-arrows: true must be set.

Custom Loot Not Appearing

  1. Run /putintothechest — is the tier shown as enabled (green)?
  2. Are there items saved? Check the item count in the main menu.
  3. Is the fraction too low? 1/10 of 5 items = 0–1 items per chest.
  4. Is the correct tier spawning? Configure all three tiers or adjust chest chances.

Pre-Open Timer Issues

Chest can be opened immediately — check pre-open-timer.enabled: true.

Countdown messages not visible to nearby players — check notify-radius in config (default 20 blocks).

Timer messages sent to entire server — update to 4.4. Messages are now radius-limited.

Protection Zone Not Working

Blocks can still be broken near chest:

  • Check chest-protection-zone.enabled: true
  • If use-worldguard: true but WorldGuard isn't installed, the plugin falls back to built-in blocking — check console for errors

Zone not removed after chest opens:

  • This is a bug — report with server version and console output

Notifications Not Showing

Players with default permissions on restricted servers (all permissions denied) won't see announcements. Grant:

/lp group default permission set spawnchest.notify.spawn true
/lp group default permission set spawnchest.notify.coordinates true
/lp group default permission set spawnchest.notify.countdown true
/lp group default permission set spawnchest.notify.disappear true
/lp group default permission set spawnchest.notify.bossbar true

BossBar Not Showing

  1. features.bossbar.enabled: true in config
  2. Player has spawnchest.notify.bossbar permission
  3. Run /reloadchestconfig after enabling

BossBar visible when it should be hidden — fixed in 4.4. Both show-countdown and show-active-chest must be false to hide it.

Statistics Not Tracking

/chestconfig get statistics.enabled

Check write permissions for statistics.yml:

chmod 644 plugins/SpawnChestPlugin/statistics.yml

Check disk space: df -h

Performance

TPS drops on chest spawn:

features:
  effects:
    particles:         false
    chest-beacon-beam: false
  guardians:
    common-count:    1
    rare-count:      2
    legendary-count: 3

Increase spawn interval: /setchesttimer 1800

Particle error in console:

IllegalArgumentException: missing required data class java.lang.Float

This is fixed in 4.4 — update to resolve.

Language / Encoding Issues

Weird characters (æ, â, ë) — language file not saved as UTF-8. Open in VS Code or Notepad++ and convert encoding before saving.

Message shows key instead of text (e.g. gui.save-button) — key is missing from your language file. Add it manually or delete the file and let the plugin regenerate it.

Wrong language showing:

/chestconfig set language ru
/reloadchestconfig

Commands Not Working

"Unknown command" — another plugin may have the same command. Try the namespaced version:

/spawnchestplugin:chestnow

Permission denied — check with LuckPerms:

/lp user <player> permission check spawnchest.admin
/lp user <player> permission set spawnchest.admin true

Console Error Reference

Error Cause Fix
UnsupportedClassVersionError Java too old Upgrade to Java 17+
NoClassDefFoundError Corrupted JAR Re-download
InvalidConfigurationException YAML syntax error Validate config at yamllint.com
IllegalArgumentException: missing required data class Float Particle API change in 1.21.10+ Update to 4.4
OutOfMemoryError Server out of RAM Increase -Xmx in startup script

Getting Help

Before asking, gather:

  1. Plugin version — check plugins/SpawnChestPlugin/ folder name or startup log
  2. Server version — /version
  3. Full console error including stack trace (not a screenshot)
  4. Relevant config section

Support channels:

Good bug report:

Plugin: SpawnChestPlugin 4.4
Server: Paper 1.21.11
Java: 21

Issue: /chestnow spawns only 1 chest when chest-count-per-interval is set to 3


Steps:


    

  1. /chestconfig set settings.chest-count-per-interval 3
    2. 

  2. /chestnow
    3. 

  3. Only 1 chest spawns
    4. 



Console output:
[SpawnChest] Batch spawn: 3 chest(s), 5s apart.
[SpawnChest] Spawn in progress (4s ago)   ← appears for chest 2 and 3
# Troubleshooting

Plugin Not Loading

Check Java version — must be 17 or newer:

java -version

Error UnsupportedClassVersionError → upgrade Java. Download from Adoptium.

Check server software — Vanilla does not support plugins. Use Spigot, Paper, or Purpur.

Corrupted JAR — if file is 0 KB or download was interrupted, delete and re-download.

Linux permissions:

chmod 644 plugins/SpawnChestPlugin*.jar
chmod 755 plugins/SpawnChestPlugin/

Chests Not Spawning

Run these in order:

/nextchest          # is the timer still counting?
/chestnow           # force spawn — does it work?
/testchestzone      # do the sample coordinates look valid?
/chestconfig get settings.enabled-worlds

World not in list — add it:

/chestconfig set settings.enabled-worlds [world,your_world]

No valid location found — spawn zone may be too small or all surfaces excluded:

settings:
  spawn-zone:
    min-distance: 200
    max-distance: 5000
    exclude-surfaces:
      water: true
      lava:  true

YAML error — malformed config prevents loading. Validate at yamllint.com, fix the reported line, then /reloadchestconfig.

Common YAML mistakes:

# Wrong — tab indentation
	spawn-interval-seconds: 600

# Wrong — missing space after colon
enabled:true

# Correct
enabled: true
spawn-interval-seconds: 600

Batch Spawn (3 chests configured, fewer spawn)

Check chest-count-per-interval:

/chestconfig get settings.chest-count-per-interval

If the second or third chest shows "Spawn in progress" warning in console, the batch queue is competing with itself. This is fixed in 4.4 — update if using an older version.

Legendary Items Not Working

/chestconfig get legendary-items.enabled
/chestconfig get legendary-items.<item>.enabled
/cooldowns
/chestconfig get abilities.pvp-protection

If pvp-protection: true, abilities do not trigger against other players — this is intentional.

Phoenix Feather not resurrecting — must be in inventory when death occurs. Killed by /kill is not protected.

Master Pickaxe not smelting — works on Iron, Gold, Copper, Ancient Debris only. Diamond/Emerald/Coal drop normally.

Void Shovel not digging 3×3 — must hold Shift while breaking a diggable block.

Guardian Bow not homing — targets must be within homing-range blocks of the arrow, and homing-arrows: true must be set.

Custom Loot Not Appearing

  1. Run /putintothechest — is the tier shown as enabled (green)?
  2. Are there items saved? Check the item count in the main menu.
  3. Is the fraction too low? 1/10 of 5 items = 0–1 items per chest.
  4. Is the correct tier spawning? Configure all three tiers or adjust chest chances.

Pre-Open Timer Issues

Chest can be opened immediately — check pre-open-timer.enabled: true.

Countdown messages not visible to nearby players — check notify-radius in config (default 20 blocks).

Timer messages sent to entire server — update to 4.4. Messages are now radius-limited.

Protection Zone Not Working

Blocks can still be broken near chest:

  • Check chest-protection-zone.enabled: true
  • If use-worldguard: true but WorldGuard isn't installed, the plugin falls back to built-in blocking — check console for errors

Zone not removed after chest opens:

  • This is a bug — report with server version and console output

Notifications Not Showing

Players with default permissions on restricted servers (all permissions denied) won't see announcements. Grant:

/lp group default permission set spawnchest.notify.spawn true
/lp group default permission set spawnchest.notify.coordinates true
/lp group default permission set spawnchest.notify.countdown true
/lp group default permission set spawnchest.notify.disappear true
/lp group default permission set spawnchest.notify.bossbar true

BossBar Not Showing

  1. features.bossbar.enabled: true in config
  2. Player has spawnchest.notify.bossbar permission
  3. Run /reloadchestconfig after enabling

BossBar visible when it should be hidden — fixed in 4.4. Both show-countdown and show-active-chest must be false to hide it.

Statistics Not Tracking

/chestconfig get statistics.enabled

Check write permissions for statistics.yml:

chmod 644 plugins/SpawnChestPlugin/statistics.yml

Check disk space: df -h

Performance

TPS drops on chest spawn:

features:
  effects:
    particles:         false
    chest-beacon-beam: false
  guardians:
    common-count:    1
    rare-count:      2
    legendary-count: 3

Increase spawn interval: /setchesttimer 1800

Particle error in console:

IllegalArgumentException: missing required data class java.lang.Float

This is fixed in 4.4 — update to resolve.

Language / Encoding Issues

Weird characters (æ, â, ë) — language file not saved as UTF-8. Open in VS Code or Notepad++ and convert encoding before saving.

Message shows key instead of text (e.g. gui.save-button) — key is missing from your language file. Add it manually or delete the file and let the plugin regenerate it.

Wrong language showing:

/chestconfig set language ru
/reloadchestconfig

Commands Not Working

"Unknown command" — another plugin may have the same command. Try the namespaced version:

/spawnchestplugin:chestnow

Permission denied — check with LuckPerms:

/lp user <player> permission check spawnchest.admin
/lp user <player> permission set spawnchest.admin true

Console Error Reference

Error Cause Fix
UnsupportedClassVersionError Java too old Upgrade to Java 17+
NoClassDefFoundError Corrupted JAR Re-download
InvalidConfigurationException YAML syntax error Validate config at yamllint.com
IllegalArgumentException: missing required data class Float Particle API change in 1.21.10+ Update to 4.4
OutOfMemoryError Server out of RAM Increase -Xmx in startup script

Getting Help

Before asking, gather:

  1. Plugin version — check plugins/SpawnChestPlugin/ folder name or startup log
  2. Server version — /version
  3. Full console error including stack trace (not a screenshot)
  4. Relevant config section

Support channels:

Good bug report:

Plugin: SpawnChestPlugin 4.4
Server: Paper 1.21.11
Java: 21

Issue: /chestnow spawns only 1 chest when chest-count-per-interval is set to 3

Steps:
1. /chestconfig set settings.chest-count-per-interval 3
2. /chestnow
3. Only 1 chest spawns

Console output:
[SpawnChest] Batch spawn: 3 chest(s), 5s apart.
[SpawnChest] Spawn in progress (4s ago)   ← appears for chest 2 and 3

Clone this wiki locally