WHAT WAS DONE:
Created comprehensive task documentation for fixing Whitelist Manager after Panel v1.12.1 API breaking changes
PROBLEM IDENTIFIED:
- Whitelist Manager built against Panel v1.11.x API (February 2026)
- Panel upgraded to v1.12.1 on March 13, 2026
- API response format changed between versions
- All servers showing "UNKNOWN" status
- Server grouping broken (wrong counts, unknown servers)
- Status detection completely broken
ROOT CAUSE:
Python code still parsing old v1.11.x API format. Panel v1.12.1 changed:
- feature_limits → limits
- whitelist → whitelist_enabled
- Possible: environment variable structure
- Possible: nested object changes
IMPACT:
- ❌ Status detection broken (all servers show UNKNOWN)
- ❌ Server grouping broken (TX1 wrong count, unknown group appeared)
- ✅ Core functions likely still work (add/remove player)
- ✅ Workaround exists (use Panel console)
TASK DETAILS:
- Time estimate: 1-2 hours
- Priority: Tier 3 (workaround exists)
- Status: TO DO - BROKEN (needs fix when home)
FIX PROCEDURE DOCUMENTED:
1. SSH to Billing VPS (38.68.14.188)
2. Check service logs for API errors
3. Test Pterodactyl API manually to see new format
4. Update Python code to parse v1.12.1 format
5. Add fallback support for v1.11.x (backward compatibility)
6. Test with live servers
7. Restart service
8. Verify all servers show correct status
CODE CHANGES NEEDED (EXAMPLE):
Before: server['attributes']['feature_limits']['whitelist']
After: server['attributes']['limits']['whitelist_enabled']
Plus: Add .get() safety, fallback to old format, better error handling
CRITICAL REMINDER ADDED:
**ALWAYS check Whitelist Manager after Panel or Wings updates!**
Pterodactyl API can change between minor versions. After ANY Panel/Wings update:
1. Visit whitelist.firefrostgaming.com
2. Verify server statuses (not all UNKNOWN)
3. Check server grouping (correct counts)
4. Test add/remove player
5. If broken → Task #86 fix procedure
PREVENTION DOCUMENTATION:
- Post-update checklist created
- Version compatibility matrix started
- Health check endpoint design
- API versioning notes
- Best practices for defensive coding
WORKAROUND UNTIL FIXED:
Use Pterodactyl Panel console directly:
1. panel.firefrostgaming.com
2. Select server → Console tab
3. Commands: whitelist add/remove <username>
FUTURE ENHANCEMENTS:
- Panel version detection
- API format auto-detection
- /health endpoint for monitoring
- Better error messages
- Retry logic for failed API calls
WHY THIS MATTERS:
Whitelist Manager saves 96.7% time (15 min → 30 sec). That value is lost while broken. Fix is probably trivial (2-5 lines of code) but critical for operational efficiency.
This also establishes pattern: Any Panel/Wings update can break integrations. Must test ALL custom tools after updates.
FILES CREATED:
- docs/tasks/whitelist-manager-v1-12-compatibility/README.md (10,500+ words)
FILES MODIFIED:
- docs/core/tasks.md (added Task #86)
RELATED TASKS:
- Task #7: Whitelist Manager (original deployment)
- Task #47: Whitelist Manager Refinements (Mayview grouping)
- Task #3: Pterodactyl Panel Update v1.12.1 (what broke it)
Signed-off-by: The Versionist (Chronicler #49) <claude@firefrostgaming.com>
43dcec8bd9