firefrost-operations-manual/docs/tasks/whitelist-manager-v1-12-compatibility

Task #86: Whitelist Manager - Panel v1.12.1 API Compatibility Fix

Status: IDENTIFIED - Ready to fix
Owner: Michael "Frostystyle" Krause
Priority: Tier 3 - Enhancement (workaround exists)
Created: March 30, 2026
Time Estimate: 1-2 hours

---

⚠️ CRITICAL REMINDER

ALWAYS check Whitelist Manager after Panel or Wings updates!

Pterodactyl API format can change between versions. When you update Panel or Wings, immediately verify Whitelist Manager is still functioning correctly.

Quick check after updates:

1. Visit whitelist.firefrostgaming.com
2. Verify server statuses show correctly (not all "UNKNOWN")
3. Test add/remove player on one server
4. Check Recent Activity log

If broken, refer to this task for fix procedure.

---

Problem Statement

What's Broken:

• Whitelist Manager dashboard at whitelist.firefrostgaming.com
• All servers showing "UNKNOWN" status
• Status badges not displaying (WHITELISTED/PUBLIC/OFF)
• Server grouping incorrect (wrong counts, unknown servers)

Root Cause:

• Whitelist Manager built against Pterodactyl Panel v1.11.x API (February 2026)
• Panel upgraded to v1.12.1 on March 13, 2026
• API response format changed between versions
• Python code still parsing old v1.11.x format
• Status detection code failing silently

Impact:

• ⚠️ Status detection broken (cosmetic)
• ✅ Core functions likely still work (add/remove player)
• ✅ Workaround available (use Panel console directly)

---

Screenshots

Current broken state (March 30, 2026):

• All servers: "UNKNOWN" status
• TX1 shows "5 servers" but lists more
• NC1 shows "2 servers" but has more
• "Unknown (4 servers)" group appeared
• Recent Activity still logging (service running)

---

Technical Details

What Changed in Panel v1.12.1

API response structure changed.

v1.11.x format (what Whitelist Manager expects):

{
  "attributes": {
    "name": "Stoneblock 4 - TX",
    "feature_limits": {
      "whitelist": true
    },
    "environment": {
      "WHITELIST_ENABLED": "true"
    }
  }
}

v1.12.1 format (what Panel now returns - SUSPECTED):

{
  "attributes": {
    "name": "Stoneblock 4 - TX",
    "limits": {
      "whitelist_enabled": true
    },
    "container": {
      "environment": {
        "WHITELIST_ENABLED": "true"
      }
    }
  }
}

Key changes:

• feature_limits → limits
• whitelist → whitelist_enabled
• environment moved under container
• Possible: field names changed (camelCase vs snake_case)

Where the Code Is Broken

Location: Billing VPS (38.68.14.188)
Service: whitelist-manager (systemd)
Code location: /opt/whitelist-manager/ or /var/www/whitelist-manager/ (verify)

Files likely affected:

1. Main Flask app (app.py, whitelist.py, or main.py)
2. Pterodactyl API integration module
3. Server status detection function
4. Server grouping logic

Specific functions to check:

• get_server_status(server) - status detection
• parse_server_response(data) - API parsing
• group_servers_by_node(servers) - grouping logic

---

Fix Procedure

Step 1: Access Billing VPS

ssh architect@38.68.14.188

Step 2: Locate Whitelist Manager Code

# Common locations
ls -la /opt/whitelist-manager/
ls -la /var/www/whitelist-manager/
ls -la /home/architect/whitelist-manager/

# Or find it
sudo find / -name "whitelist*" -type d 2>/dev/null | grep -v node_modules

Step 3: Check Service Logs

# View recent errors
sudo journalctl -u whitelist-manager -n 100 --no-pager

# Filter for API errors
sudo journalctl -u whitelist-manager | grep -i "error\|fail\|api" | tail -50

# Look for KeyError or AttributeError (common in dict parsing)
sudo journalctl -u whitelist-manager | grep -i "KeyError\|AttributeError" | tail -20

Step 4: Test Pterodactyl API Manually

# Get Panel API key from environment or config
sudo cat /opt/whitelist-manager/.env | grep PTERODACTYL_API_KEY
# Or
sudo systemctl show whitelist-manager | grep API_KEY

# Test API endpoint
curl -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  https://panel.firefrostgaming.com/api/application/servers \
  | python3 -m json.tool > /tmp/panel-api-response.json

# Review the response structure
less /tmp/panel-api-response.json

Look for:

• Where server status/whitelist info is located
• Field names (whitelist vs whitelist_enabled)
• Structure changes (nested objects)

Step 5: Update Python Code

Navigate to code directory:

cd /opt/whitelist-manager  # or wherever it's located
source venv/bin/activate    # activate virtual environment

Find status detection code:

grep -r "feature_limits" .
grep -r "get_server_status" .
grep -r "WHITELISTED" .

Example fix (BEFORE):

def get_server_status(server):
    """Detect if server has whitelist enabled"""
    try:
        if server['attributes']['feature_limits']['whitelist']:
            return "WHITELISTED"
        return "PUBLIC"
    except KeyError:
        return "UNKNOWN"

Example fix (AFTER):

def get_server_status(server):
    """Detect if server has whitelist enabled - Panel v1.12.1 compatible"""
    try:
        attrs = server.get('attributes', {})
        
        # Try v1.12.x format first
        limits = attrs.get('limits', {})
        if limits.get('whitelist_enabled', False):
            return "WHITELISTED"
        
        # Fallback to v1.11.x format for compatibility
        feature_limits = attrs.get('feature_limits', {})
        if feature_limits.get('whitelist', False):
            return "WHITELISTED"
        
        return "PUBLIC"
    except Exception as e:
        print(f"Error detecting server status: {e}")
        return "UNKNOWN"

Key changes:

• Use .get() instead of direct dict access (safer)
• Try new format first, fallback to old
• Better error handling
• Log errors for debugging

Step 6: Update Server Grouping (If Broken)

Find grouping code:

grep -r "group.*server" .
grep -r "TX1\|NC1" .

Check for:

• Node detection logic (how it determines TX1 vs NC1)
• Possibly using server IP or name patterns
• May need to update if Panel changed how node info is returned

Step 7: Test Changes

# Stop service
sudo systemctl stop whitelist-manager

# Run in debug mode
python3 app.py --debug
# Or
flask run --debug

# Check for errors in output
# Test in browser: http://38.68.14.188:5000

Verify:

• Servers load correctly
• Statuses show (WHITELISTED/PUBLIC/OFF)
• Grouping correct (TX1 = 5 servers, NC1 = 6 servers)
• Add/remove player still works

Step 8: Restart Service

# If running in debug, stop it (Ctrl+C)

# Restart production service
sudo systemctl restart whitelist-manager

# Check status
sudo systemctl status whitelist-manager

# Verify no errors
sudo journalctl -u whitelist-manager -n 20 --no-pager

Step 9: Verify in Browser

Visit: https://whitelist.firefrostgaming.com

Check:

• ✅ Server statuses display correctly
• ✅ TX1: 5 servers group
• ✅ NC1: 6 servers group
• ✅ No "Unknown" group (unless actual unknown servers)
• ✅ Add player works
• ✅ Remove player works
• ✅ Recent Activity logs correctly

Step 10: Document Changes

Update this file with:

• Exact code changes made
• API format differences found
• Any gotchas for future updates

Add note to Panel update checklist:

• Always verify Whitelist Manager after Panel updates
• Test server status detection
• Reference this task if broken

---

Prevention for Future Updates

Create Post-Update Checklist

After ANY Panel or Wings update:

1. ✅ Visit whitelist.firefrostgaming.com
2. ✅ Verify server statuses (not all "UNKNOWN")
3. ✅ Check server grouping (correct counts)
4. ✅ Test add player to one server
5. ✅ Test remove player from one server
6. ✅ Check Recent Activity log
7. ✅ If broken → Task #86 fix procedure

Add to Panel update documentation: "After Panel update, immediately verify Whitelist Manager functionality. See Task #86 for fix procedure if API compatibility broken."

Version Compatibility Matrix

Panel Version	Whitelist Manager Status	Notes
v1.11.x	✅ Working	Original development version
v1.12.0	❓ Unknown	Not tested
v1.12.1	❌ BROKEN	Status detection fails - needs update
v1.13.x	❓ Future	Test immediately after upgrade

Update this table after each Panel upgrade.

---

Workaround (Until Fixed)

Use Pterodactyl Panel console directly:

1. Go to https://panel.firefrostgaming.com
2. Navigate to Servers
3. Select server
4. Click "Console" tab
5. Type commands:
   • whitelist add <username>
   • whitelist remove <username>
   • whitelist list

Or SSH to nodes:

# TX1 Dallas
ssh architect@38.68.14.26

# NC1 Charlotte
ssh architect@216.239.104.130

Then use Pterodactyl console from Panel.

---

Dependencies

Blocks: Nothing (workaround exists)

Blocked By: Nothing (ready to fix)

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)

---

Success Criteria

Fix is complete when:

• ✅ All servers show correct status (WHITELISTED/PUBLIC/OFF)
• ✅ Server grouping correct (TX1: 5 servers, NC1: 6 servers)
• ✅ No "Unknown" group (unless legitimate unknown servers)
• ✅ Add player function works
• ✅ Remove player function works
• ✅ Bulk operations work (add/remove to ALL)
• ✅ Recent Activity logs correctly
• ✅ Code updated to handle both v1.11.x and v1.12.x API formats
• ✅ Documentation updated with fix details
• ✅ Post-update checklist added to Panel update procedure

---

Technical Notes

API Versioning

Pterodactyl does NOT use semantic API versioning. The API is tightly coupled to Panel version.

This means:

• Minor Panel updates (1.11 → 1.12) can break API compatibility
• No deprecation warnings
• No API changelog
• Must test integrations after EVERY Panel update

Best practice:

• Write defensive code (use .get(), handle missing keys)
• Support multiple API formats when possible
• Log API responses for debugging
• Add version detection to code

Code Quality Improvements

When fixing, also improve:

1. Error handling - Better logging of API errors
2. API response caching - Reduce API calls
3. Health check endpoint - /health that tests API connectivity
4. Version detection - Log Panel version from API
5. Fallback behavior - Graceful degradation if API fails

Example health check:

@app.route('/health')
def health_check():
    """Health check endpoint - tests Panel API connectivity"""
    try:
        response = requests.get(
            f"{PANEL_URL}/api/application/servers",
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=5
        )
        if response.status_code == 200:
            data = response.json()
            return {
                "status": "healthy",
                "panel_api": "connected",
                "servers_count": len(data.get('data', []))
            }, 200
        else:
            return {
                "status": "unhealthy",
                "panel_api": "error",
                "error_code": response.status_code
            }, 500
    except Exception as e:
        return {
            "status": "unhealthy",
            "panel_api": "unreachable",
            "error": str(e)
        }, 500

---

Related Documentation

• Original Deployment: docs/tasks/whitelist-manager/
• Panel Update Log: docs/tasks/pterodactyl-panel-update/
• Infrastructure Manifest: docs/core/infrastructure-manifest.md
• Task Master List: docs/core/tasks.md

---

Future Enhancements (Phase 2)

While fixing, consider adding:

1. Panel version detection - Log Panel version on startup
2. API format auto-detection - Detect v1.11.x vs v1.12.x format
3. Health monitoring - /health endpoint for uptime monitoring
4. Better error messages - User-facing errors if API fails
5. Retry logic - Auto-retry failed API calls

Don't over-engineer - just get it working first, then iterate.

---

Fire + Frost + Foundation = Where Love Builds Legacy 💙🔥❄️

---

Document Status: ACTIVE
Task Status: IDENTIFIED - Ready to fix
Ready to Build: Yes (when home)