Troubleshooting Guide

2026-07-30

Comprehensive troubleshooting for MinerTrack Anti-XRay — common issues, solutions, and debugging techniques.

🚨 Quick Diagnostic Checklist

Before diving in, verify these basics:

Check Command / Location Expected
Plugin loaded Console startup [MinerTrack] Enabled
Config generated /plugins/MinerTrack/ config.yml, language.yml, Configuration/*.yml
Commands work /mtrack help Help menu displays
Permissions /mtrack check <you> Shows your VL (0)
Logs writing /plugins/MinerTrack/logs/ .log files appear after mining

🔍 Detection Issues

Detections Too Rare (False Negatives)

Symptoms: Known X-rayers not flagged, VL stays at 0.

Cause Solution
rare-ores missing target ores Add ores to Configuration/<world>.yml → xray.rare-ores
max-height too low Increase xray.max-height (overworld: 32→64, nether: 128)
veinCountThreshold too high Lower xray.veinCountThreshold (default 2→1)
natural-detection skipping too much Disable check_skip_vl for cave/sea/lava-sea
Player has minertrack.bypass Remove permission or set disable_bypass_permission: true
Detection disabled for world Check xray.enable: true in world config

Debug Steps:

  1. Enable verbose mode: /mtrack verbose
  2. Have test player mine rare ores
  3. Watch for [MinerTrack] [Verbose] messages
  4. If no messages → detection not triggering

Detections Too Aggressive (False Positives)

Symptoms: Legitimate players flagged, high VL on normal mining.

Cause Solution
veinCountThreshold too low Increase xray.veinCountThreshold (2→3 or 4)
max_vein_distance too high Lower xray.max_vein_distance (5→3)
natural-detection disabled Enable natural-detection.enable: true
Cave detection too strict Increase cave.air-threshold (14→20), decrease CaveAirMultiplier (5→3)
path-detection thresholds too low Increase turn-count-threshold, branch-count-threshold
Server has custom ore generation Adjust rare-ores to match actual rare ores

Recommended Conservative Config:

xray:
  veinCountThreshold: 3
  max_vein_distance: 3
  natural-detection:
    enable: true
    cave:
      air-threshold: 18
      CaveAirMultiplier: 3
      check_skip_vl: true
    sea:
      check_skip_vl: true
    lava-sea:
      check_skip_vl: true

Specific World Issues

Nether: Ancient Debris Not Detected

# nether.yml
rare-ores:
  - minecraft:ancient_debris
  # Add modded nether ores if applicable

End: False Positives on Chorus Fruit/End Stone

# end.yml
xray:
  enable: false  # Disable unless you have rare end ores

Custom Dimensions

  • Create Configuration/<namespace>_<dimension>.yml
  • Copy from overworld.yml and adjust rare-ores
  • Use correct namespace IDs (e.g., mymod:my_dimension)

🔔 Discord Webhook Issues

Webhook Not Firing

Check Solution
DiscordWebHook.enable: true Set to true in config.yml
WebHookURL valid Test URL in browser / Discord webhook tester
Player VL ≥ vl-required Default is 4 — check /mtrack check <player>
Server can reach Discord Test: curl -X POST <webhook_url> from server
Custom JSON valid Validate JSON at jsonlint.com

Webhook Firing Too Much

DiscordWebHook:
  vl-required: 6  # Increase from default 4

Custom JSON Not Working

custom-json:
  enable: true
  format: |
    {
      "content": "X-Ray Alert: %player% (VL: %player_vl%)",
      "embeds": [{
        "title": "Detection Details",
        "fields": [
          {"name": "Ore", "value": "%ore_type% x%ore_count%", "inline": true},
          {"name": "Location", "value": "%world% %pos_x% %pos_y% %pos_z%", "inline": true}
        ]
      }]
    }

Test Custom JSON:

  1. Set custom-json.enable: true
  2. Use simple JSON first
  3. Check Discord for formatting errors
  4. Validate all placeholders resolve

📝 Log File Issues

Logs Not Writing

Check Solution
log_file: true Enable in config.yml
Folder permissions Server user must write to /plugins/MinerTrack/logs/
Disk space Check df -h on server
delete_time not deleting Set delete_time: 30 (days), -1 = never delete

Log Format Wrong

Edit language.yml:

log-format: '%year%-%month%-%day% %hour%:%minute%:%second% | %player% failed X-Ray check VL:%vl%(+%add_vl%) Block:%block_type%x%count%(Veinx%vein_count%) World: %world% Pos: X%pos_x% Y%pos_y% Z%pos_z%'

Viewing Logs In-Game

/mtrack logs 2024-01-15.log
/mtrack logs 2024-01-15.log 2  # Page 2

Errors:

  • "Log file not found" → Check exact filename in /plugins/MinerTrack/logs/
  • "Only can view log file" → Must end with .log
  • "Page number out of range" → Use valid page number

⚡ Performance Issues

High CPU / Lag

Cause Solution
Too many players mining Normal — detection is lightweight
max_path_length too high Reduce from 500 to 300
detection-range too high Reduce natural-detection.cave.detection-range from 3 to 2
Folia region contention Update to latest Folia + MinerTrack
Debug mode enabled Set debug: false in config.yml

Memory Leaks

  • Not typical — MinerTrack clears path history on trace_remove (default 15 min after VL=0)
  • If suspected: Restart server, monitor heap with /mtrack verbose off

🔧 Platform-Specific Issues

Paper / Purpur

Issue Solution
"Unsupported class version" Use Java 17+ (Java 21 for 1.21+)
Async chunk loading conflicts Update Paper to latest build
API version mismatch Match MinerTrack version to Paper version

Folia (Regionized)

Issue Solution
Region scheduling errors Update MinerTrack to latest (Folia support added v2.0+)
Cross-region detection Detection runs per-region — normal behavior

Spigot / CraftBukkit

Not Supported. MinerTrack requires Paper APIs.

  • Solution: Migrate to Paper/Purpur/Folia

Fabric / Forge Servers

Use MinerTrack Fabric Module (separate download):

  • Modrinth: Search "MinerTrack Fabric"
  • Different installation (mods folder, not plugins)
  • Same configuration structure

🐛 Debug Mode

Enable only for debugging — verbose console output!

# config.yml
debug: true

What Debug Logs Show:

  • Ore detection events
  • Path analysis calculations
  • Natural detection checks
  • VL changes
  • Webhook send attempts

Disable immediately after debugging:

debug: false

📊 Understanding Detection Logic

Violation Level (VL) Calculation

1. Player mines rare ore (from rare-ores list)
2. Check if in natural environment (cave/water/lava)
   - If yes AND check_skip_vl: true → NO VL increase
3. Check vein distance from last vein
   - If ≤ max_vein_distance → SAME vein, no VL increase
4. Increment vein count
5. If vein count ≥ veinCountThreshold → VL++
6. Path analysis runs (turns, branches, Y-changes)
   - Exceeding thresholds → additional VL++
7. VL decays over time (config.yml decay settings)

Default Decay Settings

decay:
  interval: 3        # Check every 3 minutes
  amount: 1          # Reduce VL by 1 per interval
  use_factor: false  # Linear decay
  factor: 0.9        # Exponential decay (if use_factor: true)

With defaults: VL 5 → 0 in ~15 minutes of clean mining.

🆘 Common Error Messages

Error Cause Fix
Could not pass event BlockBreakEvent Plugin conflict Check other anti-cheat plugins
Invalid config version Config version mismatch Delete config, let regenerate (backup first!)
Webhook returned 404 Invalid webhook URL Regenerate webhook in Discord
Player not found Offline player Use exact name or UUID
No permission Missing permission node Grant required permission

🔄 Configuration Reset

Nuclear option — restores all defaults:

# 1. Stop server
# 2. Backup current config
cp -r /plugins/MinerTrack /plugins/MinerTrack.backup

# 3. Delete config folder
rm -rf /plugins/MinerTrack

# 4. Start server → fresh configs generated
# 5. Re-apply your custom settings

📞 Getting Help

Before Asking

  1. Check this troubleshooting guide
  2. Check FAQ
  3. Enable debug: true temporarily
  4. Collect:
    • Server version (Paper/Purpur/Folia + build)
    • Java version (java -version)
    • MinerTrack version (/mtrack update or JAR filename)
    • Relevant config snippets
    • Console logs (pastebin/gist)

Support Channels

Channel Best For
Discord Real-time help, quick questions
GitHub Issues Bug reports, feature requests
GitHub Discussions Configuration help, general questions

Discord: https://discord.gg/MzTea2W9cb
GitHub: https://github.com/At87668/MinerTrack/issues