Skip to content

Troubleshooting.md

Jump to bottom
Fragmer2 edited this page Feb 3, 2026 · 5 revisions

Troubleshooting Guide

Common Issues & Solutions

Issue: Plugin Not Loading

Symptoms

  • Plugin not in /plugins list
  • No folder created
  • Console shows errors

Solution 1: Check Java Version

Error:

java.lang.UnsupportedClassVersionError: com/myplugin/SpawnChestPlugin 
has been compiled by a more recent version of the Java Runtime

Fix:

# Check Java version
java -version

# Should show Java 17 or newer
# If older, update Java

Download Java 17+:

Solution 2: Check Server Software

Error:

Could not load 'plugins/SpawnChestPlugin.jar'

Check server type:

/version

Should show:

  • ✅ Spigot 1.18+
  • ✅ Paper 1.18+
  • ✅ Purpur 1.18+
  • ❌ CraftBukkit (outdated)
  • ❌ Vanilla (no plugin support)

Fix: Upgrade to Paper (recommended):

Solution 3: Corrupted JAR File

Symptoms:

  • File size is 0 KB
  • Download incomplete

Fix:

  1. Delete current JAR
  2. Re-download from official source
  3. Verify file size (should be 500KB+)
  4. Check MD5/SHA hash if provided

Solution 4: File Permissions

Linux/Unix error:

Permission denied: SpawnChestPlugin.jar

Fix:

# Navigate to plugins folder
cd /path/to/server/plugins

# Set correct permissions
chmod 644 SpawnChestPlugin*.jar

# Set folder permissions
chmod 755 SpawnChestPlugin/

Issue: Chests Not Spawning

Diagnostic Steps

Step 1: Check Timer

/nextchest

If shows time:

  • Plugin working
  • Wait for timer
  • Or use /chestnow to test

If shows error:

  • Go to Step 2

Step 2: Check Enabled Worlds

/chestconfig get settings.enabled-worlds

If shows [] (empty):

  • Spawns in ALL worlds

If shows specific worlds:

Value: [world, world_nether]
  • Check you're in enabled world
  • Add your world:
/chestconfig set settings.enabled-worlds [world,your_world_name]

Step 3: Test Manual Spawn

/chestnow

If chest spawns:

  • ✅ Plugin works
  • ❌ Timer issue
  • Fix: /resettimer

If chest doesn't spawn:

  • Check console for errors
  • Go to Step 4

Step 4: Check Console Errors

Common errors:

Error 1: World Not Loaded

[SpawnChestPlugin] ERROR: World 'world' not found!

Fix:

  • Check world name spelling
  • Make sure world is loaded
  • Edit enabled-worlds list

Error 2: No Valid Location Found

[SpawnChestPlugin] WARNING: Could not find valid spawn location after 100 attempts

Causes:

  • Spawn zone too small
  • All locations unsafe (water/lava/void)
  • World border too tight

Fix:

settings:
  spawn-zone:
    min-distance: 100        # Reduce minimum
    max-distance: 5000       # Increase maximum
    min-height: 60           # Adjust heights
    max-height: 100

Test:

/testchestzone

Error 3: All Chunks Unloaded

[SpawnChestPlugin] WARNING: Target chunk not loaded

Fix:

  • Increase spawn zone minimum distance
  • Make sure areas are loaded (spawn chunks)
  • Use chunk loaders in spawn zone

Step 5: Check Config Syntax

YAML errors:

[SpawnChestPlugin] ERROR: Could not load config.yml
org.yaml.snakeyaml.scanner.ScannerException

Common mistakes:

# ❌ WRONG - missing space after colon
enabled:true

# ✅ CORRECT
enabled: true

# ❌ WRONG - tab character
  spawn-interval-seconds: 600

# ✅ CORRECT - 2 spaces
  spawn-interval-seconds: 600

# ❌ WRONG - missing quotes
language: en

# ✅ CORRECT
language: "en"

Fix:

  1. Use YAML validator: http://www.yamllint.com/
  2. Copy error section to validator
  3. Fix syntax
  4. Reload: /reloadchestconfig

Issue: Legendary Items Not Working

Diagnostic Steps

Step 1: Check Global Toggle

/chestconfig get legendary-items.enabled

If false:

/togglelegendary

Step 2: Check Specific Item

/chestconfig get legendary-items.dragon-slayer-sword.enabled

If false:

/togglelegendary dragon-slayer-sword

Step 3: Check Cooldown

/cooldowns

If on cooldown:

  • Wait for cooldown to finish
  • Or reduce cooldown in config:
legendary-items:
  dragon-slayer-sword:
    cooldown-ms: 1000  # 1 second

Step 4: Check PvP Protection

If item doesn't work on players:

/chestconfig get abilities.pvp-protection

If true:

  • Items DON'T work on players (intended)
  • This prevents OP PvP

To enable PvP:

/chestconfig set abilities.pvp-protection false

Step 5: Verify Item is Legendary

Check item has:

  • Custom name with color codes
  • Lore (description)
  • High-level enchantments
  • Glowing effect (Unbreaking enchant)

If missing:

  • Item is fake/copied
  • Get real item: /getlegendaryitems

Specific Item Issues

Phoenix Feather Not Resurrecting

Checklist:

  1. Feather in inventory when died?
  2. Resurrection enabled in config?
/chestconfig get legendary-items.phoenix-feather.resurrection
  1. Not killed by /kill command? (doesn't protect)
  2. Not in creative mode?

Test:

1. Get feather: /getlegendaryitems
2. Put in inventory
3. Take damage in survival
4. Should resurrect at low health

Guardian Bow Not Homing

Checklist:

  1. Homing enabled?
/chestconfig get legendary-items.guardian-bow.homing-arrows
  1. Targets within 5 blocks of arrow?
  2. Not targeting players (if PvP protection on)?
  3. Targets are mobs (not armor stands)?

Test:

1. Spawn mob group
2. Shoot near them (not directly at)
3. Arrows should curve toward mobs

Master Pickaxe Not Auto-Smelting

Check ore type:

** Auto-smelts:**

  • Iron Ore → Iron Ingot
  • Gold Ore → Gold Ingot
  • Copper Ore → Copper Ingot
  • Ancient Debris → Netherite Scrap

** Does NOT auto-smelt:**

  • Diamond Ore (already drops item)
  • Emerald Ore (already drops item)
  • Coal Ore (already drops item)
  • Lapis Ore (already drops item)

If not working on correct ore:

/chestconfig get legendary-items.master-pickaxe.auto-smelt

Should be true.

Void Shovel Not Digging 3x3

Checklist:

  1. Holding SHIFT while breaking block?
  2. Breaking diggable block (dirt/sand/gravel)?
  3. Area digging enabled?
/chestconfig get legendary-items.void-shovel.area-dig-enabled
  1. Not on cooldown?

Test:

1. Get shovel: /getlegendaryitems
2. Place 5x5 dirt area
3. Hold SHIFT
4. Break center dirt
5. Should break 3x3 area

Issue: Custom Loot Not Working

Diagnostic Steps

Step 1: Check if Enabled

Open main menu:

/putintothechest

Click tier icon, check in lore:

  • ✅ "Custom loot: ENABLED" = working
  • ❌ "Custom loot: DISABLED" = not active

If disabled but you have items:

  • You didn't click Save button
  • Re-add items and click Save

Step 2: Check Item Count

Main menu shows:

Items: 0

Problem: No items in loot table

Fix:

  1. Open edit menu for tier
  2. Add items from inventory
  3. Click Save button (slot 6)

Step 3: Check Fraction

If only 0-1 items spawning:

Problem: Fraction too low

Example:

  • 5 items total
  • 1/10 fraction
  • Result: 0-1 items (5 ÷ 10 = 0.5)

Fix:

  1. Open edit menu
  2. Click fraction increase (→) button
  3. Change to 1/3 or higher
  4. Click Save

Step 4: Verify Correct Tier Spawning

Your loot:

  • Common: 10 items configured
  • Rare: Empty
  • Legendary: Empty

If Rare chest spawns:

  • Will be empty (default loot)
  • Not a bug!

Fix:

  • Configure all tiers
  • Or adjust chest chances:
chest-chances:
  common: 1.0
  rare: 0.0
  legendary: 0.0

Issue: Statistics Not Tracking

Diagnostic Steps

Step 1: Check if Enabled

/chestconfig get statistics.enabled

If false:

/togglefeature statistics

Step 2: Check File Permissions

Linux error:

[SpawnChestPlugin] ERROR: Could not save statistics.yml
java.io.IOException: Permission denied

Fix:

cd /path/to/server/plugins/SpawnChestPlugin
chmod 644 statistics.yml
chmod 755 .

Step 3: Check Disk Space

df -h

If disk full:

  • Free up space
  • Move old backups
  • Increase server storage

Issue: Performance Problems

Symptoms

  • Server TPS dropping
  • Lag spikes when chest spawns
  • Player disconnects

Diagnostic Steps

Step 1: Check TPS

/tps

Good: 19-20 TPS
Acceptable: 17-18 TPS
Bad: < 17 TPS

If TPS bad only when chest spawns:

  • Plugin issue
  • Continue troubleshooting

If TPS always bad:

  • Server hardware issue
  • Not plugin's fault

Step 2: Reduce Particle Effects

features:
  effects:
    particles: false
    chest-beacon-beam: false

Reload:

/reloadchestconfig

Impact: Reduces client/server load

Step 3: Reduce Guardian Count

features:
  guardians:
    common-count: 1      # Instead of 2
    rare-count: 2        # Instead of 3
    legendary-count: 3   # Instead of 5

Impact: Less mob AI calculations

Step 4: Increase Spawn Interval

/setchesttimer 1800  # 30 minutes instead of 10

Impact: Less frequent spawns = less lag spikes

Step 5: Check Plugin Conflicts

Common conflicts:

  • Multiple chest spawn plugins
  • Heavy world gen plugins during chest search
  • Laggy protection plugins checking chest placement

Test:

  1. Stop server
  2. Remove other plugins temporarily
  3. Start server
  4. Test chest spawn
  5. If fast → other plugin conflict

Step 6: Profile Server

Use Spark profiler:

  1. Install Spark plugin
  2. Run profiler during chest spawn
  3. Check CPU usage by plugin
  4. Share results for detailed help

Issue: Achievements Not Unlocking

Diagnostic Steps

Step 1: Check Requirements

/mystats

Example:

Chests Opened: 7

For "Treasure Hunter" (10 chests):

  • Not unlocked yet (need 3 more) NORMAL

Step 2: Check Achievement Enabled

/chestconfig get statistics.achievements.enabled

If false:

/chestconfig set statistics.achievements.enabled true

Step 3: Force Recheck (Admin)

Manual check:

  1. Open statistics.yml
  2. Find player UUID
  3. Check chests-opened.total value
  4. Check achievements.treasure-hunter.unlocked value

If requirements met but not unlocked:

  • Data corruption
  • Open GitHub issue with file

Issue: Commands Not Working

Diagnostic Steps

Step 1: Check Permission

For player commands:

/lp user YourName permission check spawnchest.admin

If doesn't have permission:

/lp user YourName permission set spawnchest.admin true

Step 2: Check Command Conflicts

Error:

Unknown command. Type "/help" for help.

Other plugin might have same command

Test with namespace:

/spawnchestplugin:chestnow

If this works:

  • Another plugin conflicts
  • Use full command format
  • Or remove conflicting plugin

Step 3: Check Console

When running command, check console for:

[SpawnChestPlugin] Error executing command: ...

Copy full error and report as bug.

Issue: Language/Translation Problems

Symptoms

  • Wrong language showing
  • Missing translations
  • Broken characters (���)

Solution 1: Set Correct Language

/chestconfig get language

Change language:

/chestconfig set language "ru"  # Russian
/chestconfig set language "en"  # English

Reload:

/reloadchestconfig

Solution 2: Fix File Encoding

For non-English languages (Russian, Ukrainian, Chinese, etc.):

Problem: File must be UTF-8 encoded

Fix (Windows):

  1. Open language file in Notepad++
  2. Encoding → Convert to UTF-8
  3. Save file
  4. Reload config

Fix (Linux):

iconv -f ISO-8859-1 -t UTF-8 ru.yml > ru_fixed.yml
mv ru_fixed.yml ru.yml

Solution 3: Restore Corrupted Language File

If messages broken:

  1. Stop server
  2. Delete corrupted file:
rm lang/ru.yml
  1. Start server (regenerates default)
  2. Re-apply custom changes

Issue: Custom Loot GUI Bugs

Issue: Can't Place Items in Chest

Causes:

  1. Clicking control buttons instead of chest area

    • Bottom row = buttons (protected)
    • Upper rows = item area

  2. Chest full

    • Single chest: 18 slots max
    • Double chest: 45 slots max
    • Remove items or toggle chest type

  3. Item is air/empty

    • Can't place nothing!

Issue: Control Buttons Not Responding

Checklist:

  1. Using LEFT click?
  • Right click doesn't work
  • Shift-click doesn't work
  • Only LEFT click
  1. Clicking correct slot?
  • Slot 1: Chest type
  • Slot 3: Decrease fraction
  • Slot 5: Increase fraction
  • Slot 6: Save
  • Slot 7: Back
  • Slot 8: Reset
  1. GUI still open?
  • Don't close and reopen mid-action

Issue: Items Disappear When Toggling Chest Type

Expected behavior:

Single → Double:

  • All items transfer

Double → Single:

  • First 18 items stay
  • Excess items DROP AT YOUR FEET
  • Check ground!

Not a bug! This is intended.

Issue: Reset Doesn't Work

Two-step confirmation required:

  1. Click Reset button (slot 8)
  2. First menu opens → click Continue (slot 11)
  3. Second menu opens → click CONFIRM (slot 11)

If cancelled early:

  • Nothing happens
  • This is safety feature

Issue: Guardians Too Strong/Weak

Too Strong

Reduce count:

guardians:
  legendary-count: 2  # Instead of 5

Reduce mob difficulty:

  • Change server difficulty
  • Use mob modifier plugin

Too Weak

Increase count:

guardians:
  legendary-count: 10

Add custom equipment (future feature)

Getting More Help

Before Asking for Help

Gather this information:

  1. Plugin version:
/version SpawnChestPlugin
  1. Server info:
/version

  1. Console errors:

    • Copy full error (not screenshot)
    • Include stack trace

  2. Config excerpt:

    • Relevant section only
    • Use pastebin for full config

  3. Steps to reproduce:

    • What you did
    • What you expected
    • What actually happened

Where to Get Help

Priority order:

  1. ** Read documentation** (you're here!)

    • Check FAQ
    • Check Troubleshooting (this page)

  2. ** Search existing issues**

    • GitHub Issues search
    • Someone may have same problem

  3. ** Ask community**

  4. ** Report bug**

    • GitHub Issues (new issue)
    • Issues: GitHub Issues
    • Include all info from above

Example Bug Report (Good)

**Plugin Version:** 4.2
**Server:** Paper 1.20.4
**Java:** 17.0.8

**Issue:** Chest doesn't spawn

**Steps to reproduce:**
1. Set spawn-interval to 60
2. Run /chestnow
3. No chest spawns

**Expected:** Chest should spawn immediately

**Console Error:**
[SpawnChestPlugin] ERROR: World 'world' not found!
at com.myplugin.ChestSpawner.spawn(ChestSpawner.java:45)

**Config:**
settings:
  enabled-worlds:
    - "world"

This is GOOD - clear, detailed, error included

Example Bug Report (Bad)

doesnt work help

This is BAD - no information, can't help

Console Error Reference

Common Errors & Fixes

NullPointerException

java.lang.NullPointerException
    at com.myplugin.CustomLootManager.getCustomLoot(CustomLootManager.java:123)

Cause: Trying to access data that doesn't exist

Common scenarios:

  • Player UUID not in statistics
  • Tier name invalid
  • Config value missing

Fix:

  • Usually auto-fixed on next action
  • If persists, report as bug

ClassCastException

java.lang.ClassCastException: java.lang.String cannot be cast to java.lang.Integer

Cause: Config value has wrong type

Example:

# ❌ WRONG - should be number
spawn-interval-seconds: "600"

# ✅ CORRECT
spawn-interval-seconds: 600

Fix:

  1. Find problematic config line
  2. Remove quotes from numbers
  3. Add quotes to strings
  4. Reload config

ConcurrentModificationException

java.util.ConcurrentModificationException

Cause: Multiple threads modifying data simultaneously

Fix:

  • Usually auto-resolves
  • If constant, report as bug
  • May indicate memory corruption

OutOfMemoryError

java.lang.OutOfMemoryError: Java heap space

Cause: Server out of RAM

Not plugin issue - server configuration problem

Fix:

  1. Increase server RAM in startup script:
java -Xms2G -Xmx4G -jar paper.jar
  1. Reduce loaded chunks
  2. Remove other plugins

Still Having Issues?

Create detailed bug report:

Include:

  1. Plugin version
  2. Server version
  3. Full console error
  4. Config excerpt
  5. Steps to reproduce

Don't include:

  • "It doesn't work" (too vague)
  • Screenshots of code (use text)
  • Entire config.yml (use pastebin)

Clone this wiki locally