Troubleshooting Guide

Common issues and how to resolve them.

Plugin Won't Load

Symptoms

• GAPE doesn't appear in /plugins list
• No GAPE folder created in plugins directory
• Error messages on server startup

Solutions

• Check Java version: GAPE requires Java 17 or higher
• Check server version: Must be Paper, Spigot, or Leaf 1.20.0+
• Check startup logs: Look for GAPE-related errors
• Verify JAR integrity: Re-download if file may be corrupted
• Check file permissions: Server must have read access to JAR

False Positives

Symptoms

• Legitimate players getting kicked
• Normal actions being blocked
• Violation alerts for non-malicious behavior

Solutions

• Increase violation thresholds: Raise to 7-10 for affected checks
• Adjust packet limits: Increase rate limits by 20-50%
• Check logs: Identify which check is triggering
• Whitelist players: Give gape.bypass to trusted staff temporarily
• Review configuration: Ensure limits match your server type

Performance Issues

Server Lag After Installing GAPE

• Enable async mode: Set async processing to true
• Reduce thread pool size: If CPU-limited, use fewer threads
• Disable expensive checks: Temporarily disable Book Exploit or NBT validation
• Check for floods: GAPE may be blocking an active attack causing overhead
• Review log verbosity: Set logging to threshold-only mode

High Memory Usage

• Reduce cache sizes: Lower maximum cache entries
• Disable database logging: Use file logging only
• Clear old logs: Enable automatic log cleanup
• Reduce violation history: Lower retention period

Players Can't Chat

Symptoms

• Chat messages not appearing
• Players getting "message blocked" notifications

Solutions

• Check rate limit settings: Increase chat packet limit to 5-7/second
• Review command spam check: Ensure it's not blocking regular chat
• Verify permissions: Players shouldn't have gape.bypass unless intended
• Check for packet size limits: Ensure chat size limit is at least 256 characters

Books/Signs Being Blocked

Symptoms

• Can't create written books
• Signs won't save text
• Formatted text being stripped

Solutions

• Increase NBT limits: Raise max sign/book NBT size
• Allow click events: Enable safe clickEvents if needed
• Adjust page limits: Increase maximum pages if blocking legitimate books
• Lower strictness: Change NBT validation from strict to normal

Alerts Not Showing

Symptoms

• Staff not seeing violation alerts
• No notifications when exploits are blocked

Solutions

• Check permissions: Staff need gape.alerts permission
• Enable alerts: Staff must run /gape alerts to toggle on
• Verify alert settings: Ensure alerts are enabled in config
• Check alert threshold: May be set too high

Config Won't Reload

Symptoms

• /gape reload doesn't apply changes
• Config edits not taking effect

Solutions

• Check YAML syntax: Invalid YAML prevents reload
• Restart server: Some settings require full restart
• Check console errors: Look for config parsing errors
• Verify file saved: Ensure config.yml was actually saved

Modded Clients Being Kicked

Symptoms

• Forge/Fabric clients can't connect
• Players with mods getting violation kicks

Solutions

• Increase custom payload limits: Raise to 20-30/second
• Whitelist mod channels: Add common mod channels to whitelist
• Higher packet limits: Mods send more packets than vanilla
• Increase payload size: Allow 64-128KB payloads

Database Connection Errors

Symptoms

• MySQL connection failed errors
• Violations not being logged to database

Solutions

• Verify credentials: Check database username/password
• Check connection string: Ensure host and port are correct
• Test database access: Verify database is accessible from server
• Switch to SQLite: Use local database if MySQL unavailable
• Check firewall: Ensure database port is open

Logs Not Being Created

Symptoms

• No violations.log file
• Logs folder empty

Solutions

• Check logging enabled: Ensure logging isn't disabled in config
• Verify file permissions: Server must have write access to logs folder
• Check log level: May be set to "none"
• Review disk space: Ensure server has free disk space

Conflicts with Other Plugins

Symptoms

• Other anti-cheat plugins causing issues
• Packet-related plugins not working

Solutions

• Load order: Ensure GAPE loads before other packet plugins
• Disable duplicate checks: Turn off overlapping features in other plugins
• Check PacketEvents version: Ensure compatible version
• Contact plugin authors: Report compatibility issues

Getting Help

Before Asking for Help

• Check latest GAPE version is installed
• Review server console logs for errors
• Check violation logs for patterns
• Try default configuration to isolate custom config issues

Information to Provide

• GAPE version
• Server version (Paper/Spigot/Leaf and Minecraft version)
• Java version
• Relevant config sections
• Console errors or violation logs
• Steps to reproduce the issue

Where to Get Help

• GitHub Issues: Report bugs and request features
• GitHub Discussions: Ask questions and share configurations
• Discord: Community support and quick answers