RankForge Troubleshooting – Common Issues & Fixes

Enable settings.debug-mode: true in config.yml and execute /rankforge reload to view verbose [DEBUG] logs in the server console when diagnosing issues.

Plugin Failed to Load / UnsupportedClassVersionError

RankForge requires Java 21 or newer. Run java -version to verify your server environment. In server hosting control panels, update the Java version runtime to Java 21+.

Placeholders Appear Raw (%rankforge_points%)

1. Ensure PlaceholderAPI is installed and enabled. The startup log must show PlaceholderAPI hooked successfully.
2. Test with /papi parse me %rankforge_points%. If this returns the expected number but another plugin shows raw text, that plugin may require special PlaceholderAPI configuration.
3. Perform a clean restart (/stop then start) rather than /reload.

Points Not Increasing on Kill

• Combat points are only awarded when the victim is killed directly by another player (getKiller()). Environmental deaths or mob kills do not grant points to anyone; the victim loses points as configured.
• Check the daily limit: settings.daily-limit.max-kills. Once reached, additional kills do not grant points until midnight resets.
• Verify that settings.fixed-points.per-kill is set to a non-zero value.

Tier Rewards Not Triggering

• Tier advancement rewards are checked upon killing an opponent. Modifying points via /rankforge setpoints or external APIs does not fire tier-up reward sequences.
• Tier rewards are awarded once per tier per player. Previously claimed tiers are recorded in claimedRewards.
• Reward commands execute in console. Check your console logs for Unknown command. The default uses eco give <player> <amount>, which should be adapted to your economy plugin.

Database Connection Failed / Local JSON Fallback

If logs display Failed to initialize database (...) followed by Falling back to local JSON storage:

• Verify hostname, port, database name, user credentials.
• Ensure the database user has permissions for CREATE TABLE, INSERT, UPDATE, and SELECT.
• Verify firewall settings allow inbound connections from the Minecraft server IP.

Sign GUI Player Search Not Opening

RankForge requires PacketEvents for the virtual sign text prompt. Without PacketEvents installed, RankForge automatically falls back to standard in-game chat prompt input. See PacketEvents Integration.