Skip to content

Troubleshooting

Jump to bottom
Vaibhav Vishwakarma edited this page Dec 27, 2025 · 1 revision

Troubleshooting Guide

This guide helps you diagnose and fix common issues with SpectatorPlusPlus. Follow these steps to resolve problems and get your plugin working smoothly.

🚨 Common Issues & Solutions

🔴 Plugin Won't Load/Enable

Symptoms:

  • Plugin doesn't appear in /plugins list
  • Console shows error on startup
  • "Plugin disabled" message

Solutions:

1. Check Server Version

# Verify your server version
/version
Fix: Ensure you're running Paper/Spigot 1.21 or newer

**2. Check Java Version**
```bash
# Check Java version
java -version

Fix: Update Java if older than Java 17

3. Check Plugin File

  • Ensure file ends with .jar
  • Verify file size is reasonable (not 0KB)
  • Download from Modrinth again

4. Check Dependencies

  • Some servers require ProtocolLib or other dependencies
  • Check console for dependency errors

🔴 Commands Not Working

Symptoms:

  • /spectator returns "Unknown command"
  • Commands don't execute
  • "No permission" even for OPs

Solutions:

  1. Verify Plugin is Enabled

text /plugins Look for "SpectatorPlusPlus" in the list

  1. Check Command Registration

bash

In server console, check for registration messages

[00:00:00 INFO]: [SpectatorPlusPlus] Registered command: spectator 3. Fix Command Conflicts

  • Check for other plugins using /spectator command
  • Try aliases: /spec or /spectate
  • Use /minecraft:spectator to force vanilla command
  1. Reload Plugin

text /spectator reload or

text /reload confirm Warning: /reload can cause issues on production servers

🔴 Permissions Issues

Symptoms:

  • "You don't have permission!"
  • OPs can use but regular players can't
  • Inconsistent permission behavior

Solutions:

1. Basic Permission Check

# For LuckPerms
/lp user <player> permission check spectatorplusplus.use

# For PermissionsEx
/pex user <player> check spectatorplusplus.use
  1. Permission Setup Examples
# Give basic access to all players
lp group default permission set spectatorplusplus.use true

# Staff with admin access
lp group staff permission set spectatorplusplus.admin true

3. OP Status Conflicts

  • Some permission systems require OP + permission
  • Try giving OP temporarily: /op <player>
  • Remove OP after testing: /deop <player>

4. World/Context Permissions

  • Check if permissions are world-specific
  • Test in different worlds
  • Use global context if needed

🔴 Spectator Lobby Issues

Symptoms:

  • Players spawn in wrong location
  • "Lobby not set" message
  • Teleport errors

Solutions:

1. Set Lobby Properly

/spectator lobby set

Requirements:

  • Must be executed by OP/admin
  • Must be in the intended lobby world
  • Run command at exact spawn location

2. Verify Lobby Location Check plugins/SpectatorPlusPlus/config.yml:

lobby:
  world: "world"
  x: 100.5
  y: 64.0
  z: 200.5

3. World Protection Conflicts

  • Check if world guard/plot protection blocks teleport
  • Test with bypass permissions
  • Adjust protection settings

4. Multi-World Servers

  • Ensure lobby world is loaded
  • Check Multiverse/other world manager settings
  • Set lobby in each world if needed

🔴 First-Person Spectating Issues

Symptoms:

  • Right-click doesn't work
  • Camera glitches
  • Can't exit spectate mode

Solutions:

1. Enable Feature Check config.yml:

first-person-spectating:
  enabled: true
  right-click-to-spectate: true

2. Permission Check

# Verify player has permission
spectatorplusplus.firstperson

3. Control Issues

  • Exit: Press Shift (sneak)
  • Switch targets: Mouse wheel
  • Inventory view: Right-click (if enabled)

4. Camera Problems

  • Try camera-inside-body: false
  • Adjust player perspective
  • Check for conflicting camera plugins

🔴 Compass GUI Problems

Symptoms:

  • Compass doesn't open GUI
  • GUI shows no players
  • Items missing from hotbar

Solutions:

1. Hotbar Slot Configuration

hotbar-items:
  compass-slot: 0  # Must be 0-8

Fix: Ensure slot numbers are 0-8

2. GUI Permissions

# Required permissions
spectatorplusplus.use
spectatorplusplus.compass

3. GUI Content Issues

  • Check show-spectators: true/false
  • Verify show-health: true
  • Ensure players are online and not vanished

4. Inventory Conflicts

  • Clear player inventory before entering spectator
  • Check for inventory save/restore plugins
  • Try with empty inventory

🔴 Performance Issues

Symptoms:

  • Lag when entering spectator
  • Server performance drops
  • Memory usage spikes

Solutions:

1. Reduce Update Intervals

# In config.yml, increase intervals
update-interval: 20  # ticks (20 = 1 second)

2. Limit Features

# Disable non-essential features
first-person-spectating:
  enabled: false
  
compass-gui:
  show-health: false
  show-gamemode: false

3. Player Limits

  • Limit simultaneous spectators
  • Implement cooldowns
  • Use permissions to restrict access

4. Server Optimization

  • Allocate more RAM
  • Use Paper with optimizations
  • Reduce view-distance

🔴 Compatibility Issues

Symptoms:

  • Conflicts with other plugins
  • Features don't work together
  • Unexpected behavior

Solutions:

1. Common Conflicts

  • Vanish plugins: Adjust visibility settings
  • Teleport plugins: Set priority/override
  • World managers: Check world teleport settings

2. Plugin Load Order

# In paper.yml or spigot.yml
plugins:
  - VanishNoPacket
  - Multiverse-Core
  - SpectatorPlusPlus  # Load after dependencies

3. Feature-Specific Fixes

Chat issues: Check chat manager plugins

Flight conflicts: Disable other flight plugins

Inventory: Check inventory save plugins

🔧 Advanced Troubleshooting Debug Mode Enable debug logging in config.yml:

debug:
  enabled: true
  log-spectator-events: true
  log-spectating-events: true

Check logs in:

logs/latest.log
plugins/SpectatorPlusPlus/debug.log


### Configuration Reset
1. Stop server
2. Rename `plugins/SpectatorPlusPlus` folder
3. Start server to generate new config
4. Compare with old config
5. Stop server and restore custom settings

### Plugin Testing Protocol
1. **Clean test**:
   - Fresh server install
   - Only SpectatorPlusPlus
   - Default configuration

2. **Incremental test**:
   - Add plugins one by one
   - Test after each addition
   - Identify conflict source

📋 Error Messages & Meanings

Common Console Errors

"Could not load 'SpectatorPlusPlus.jar'"

  • Corrupted download
  • Wrong Java version
  • Missing dependencies

"NoSuchMethodError" or "ClassNotFoundException"

  • Plugin built for different Minecraft version
  • Incompatible server software
  • Update Paper/Spigot

"World not found"

  • Lobby world unloaded
  • World name mismatch
  • Case sensitivity issues

"Player not found"

  • Player offline
  • Player in different world
  • Vanish plugin interference

🛠️ Support Tools Diagnostic Commands text

Check plugin status

/spectator version

Test permissions

/spectator help

Reload configuration

/spectator reload

Log Analysis

  1. Enable timestamps: Check exact error time
  2. Search for errors: [ERROR] or [WARN]
  3. Check startup: Look for initialization errors
  4. Player actions: Trace player-triggered errors

Server Health Check

# Basic server info
/timings report

# Memory usage
/gc

# Entity count
/entity

🚑 Emergency Fixes

Immediate Solutions

1. Disable Plugin

  1. Stop server
  2. Remove .jar from plugins folder
  3. Start server
  4. Replace with fresh download

2. Reset Player Data

# Remove player data files
plugins/SpectatorPlusPlus/playerdata/<uuid>.yml

3. Safe Reload

  1. Warn players
  2. Save worlds
  3. Use /reload confirm
  4. Monitor for issues

Rollback Procedure

  1. Backup current: Copy entire plugin folder
  2. Restore previous: Use backup from working state
  3. Test: Verify functionality
  4. Update carefully: Change one setting at a time

📞 Getting Help

Before Asking for Help

  1. ✅ Check server version (1.21+)
  2. ✅ Verify Paper/Spigot
  3. ✅ Test with default config
  4. ✅ Check console errors
  5. ✅ Try clean install

Information to Provide

  • Server version: /version
  • Plugin version: /spectator version
  • Error log: Relevant console lines
  • Config: Relevant config sections
  • Steps: How to reproduce the issue

Support Channels

  • GitHub Issues: Bug reports and feature requests
  • Discord: Quick help and community support
  • Wiki: Documentation and guides

🔄 Maintenance Tips

Regular Checks

  1. Weekly: Review error logs
  2. Monthly: Backup configurations
  3. Update: Check for new versions
  4. Test: Verify after server updates

Performance Monitoring

  • Track spectator count
  • Monitor memory usage
  • Check teleport lag
  • Review player feedback

Update Best Practices

  1. Read changelog
  2. Backup current setup
  3. Test on development server
  4. Update during maintenance window
  5. Monitor after update

✅ Quick Reference

Most Common Fixes

  1. Set lobby: /spectator lobby set
  2. Grant permissions: spectatorplusplus.use
  3. Check version: 1.21+ Paper/Spigot
  4. Fresh download: From Modrinth
  5. Debug mode: Enable in config

Don't Forget

  • ⚠️ Always backup before changes
  • 📖 Read the changelog before updating
  • 🧪 Test in development environment first
  • 🔄 Use /spectator reload not /reload
  • 🎯 One change at a time for testing

Still having issues? Check the Configuration Guide or Usage Guide for more detailed information.

Clone this wiki locally