MobileMusicAssistant/Mobile Music Assistant/DocsTroubleshooting-Loading.md

# Troubleshooting: Players/Library Not Loading

## Symptom

After successful login, the Players and Library tabs show:
- Loading spinner forever
- "No Players Found" 
- "Error Loading Players"
- Empty lists

## Debugging Steps

### 1. Check Connection Info

**In the app:**
1. Go to **Players** tab
2. Tap **Info icon** (ℹ️) in toolbar
3. Check:
   - ✅ Server URL is correct
   - ✅ "Connected" shows "Yes"
   - ✅ "WebSocket" shows "Connected"
   - ✅ "Status" shows "Authenticated"

### 2. Check Console Logs

**In Xcode:**
1. Run the app with console open (⌘+Shift+Y)
2. Look for these log messages:

**Good signs:**
```
🔵 PlayerListView: Starting to load players...
🔵 MAService.getPlayers: Sending 'players' command
✅ MAService.getPlayers: Received 3 players
✅ PlayerListView: Successfully loaded 3 players
```

**Bad signs:**
```
❌ MAService.getPlayers: Error - notConnected
❌ PlayerListView: Failed to load players: Not connected to server
```

**Or:**
```
❌ WebSocket receive error: The operation couldn't be completed
❌ Failed to decode response
```

### 3. Common Causes & Solutions

#### Cause A: WebSocket Not Connected

**Symptoms:**
- Console shows: "Not connected to server"
- Connection Info shows: WebSocket = "Disconnected"

**Solution:**
```swift
// Check if WebSocket endpoint is reachable
// For reverse proxy users:
wss://musicassistant-app.hanold.online/ws

// Test in terminal:
websocat wss://musicassistant-app.hanold.online/ws
```

**Reverse Proxy Fix:**
Ensure nginx has WebSocket support:
```nginx
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
```

#### Cause B: API Endpoint Wrong

**Symptoms:**
- Login works but nothing else loads
- Console shows: "Invalid URL" or "404"

**Solution:**
Check server URL format:
- ✅ `https://musicassistant-app.hanold.online` (no port if using reverse proxy)
- ✅ `http://192.168.1.100:8095` (with port if direct)
- ❌ `https://musicassistant-app.hanold.online:8095` (wrong if using reverse proxy on 443)

#### Cause C: Token Invalid

**Symptoms:**
- Login succeeds but API calls fail
- Console shows: "401 Unauthorized"

**Solution:**
1. Generate new long-lived token
2. In app: Settings → Disconnect
3. Login again with new token

#### Cause D: Music Assistant Commands Changed

**Symptoms:**
- "Command not found" errors
- Decoding errors

**Solution:**
- Update Music Assistant server to latest version
- Check API compatibility (Server v2.7+ required)

#### Cause E: CORS or Security Issues

**Symptoms:**
- WebSocket connects but commands fail
- Mixed content warnings

**Solution:**
- Ensure reverse proxy allows WebSocket
- Check HTTPS is properly configured
- Verify no CORS blocking

### 4. Test WebSocket Directly

**Terminal test:**
```bash
# Install websocat
brew install websocat

# Test WebSocket connection
websocat wss://musicassistant-app.hanold.online/ws

# Should see connection open
# Press Ctrl+C to close
```

**With authentication:**
```bash
# You'll need to send auth first
# This is complex - use app debugging instead
```

### 5. Test API Endpoints

**Test REST API:**
```bash
# Get players (won't work without WebSocket but tests connectivity)
curl -X POST https://musicassistant-app.hanold.online/api/players \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"
```

### 6. Enable Detailed Logging

The app now includes print statements for debugging.

**What to look for in console:**

**1. Connection Phase:**
```
[INFO] Connecting to Music Assistant
[INFO] Connecting to wss://...
[INFO] Connected successfully
```

**2. Loading Phase:**
```
🔵 PlayerListView: Starting to load players...
🔵 MAService.getPlayers: Sending 'players' command
[DEBUG] Sending command: players (ID: ABC-123)
```

**3. Response Phase:**
```
[DEBUG] Received event: player_updated
✅ MAService.getPlayers: Received 3 players
```

**4. Error Messages:**
```
❌ WebSocket receive error: ...
❌ Failed to decode response: ...
❌ Request timeout
```

### 7. Check Music Assistant Server

**On the server:**
```bash
# Check Music Assistant is running
systemctl status music-assistant

# Check logs
journalctl -u music-assistant -f

# Look for:
# - WebSocket connection attempts
# - Authentication success/failure
# - Command processing
# - Errors
```

**Expected in server logs:**
```
[INFO] WebSocket connection from 192.168.1.X
[INFO] Client authenticated: user@example.com
[DEBUG] Received command: players
[DEBUG] Sent response: players (3 items)
```

## Quick Fixes

### Fix 1: Reconnect

**In app:**
1. Players tab → Info icon → **Reconnect**
2. Or: Settings → **Disconnect** → Login again

### Fix 2: Clear Cache

**In Xcode:**
1. Product → Clean Build Folder
2. Delete app from simulator/device
3. Rebuild and run

### Fix 3: Check WebSocket in nginx

**Add logging:**
```nginx
location /ws {
    access_log /var/log/nginx/websocket.log;
    error_log /var/log/nginx/websocket_error.log;
    
    proxy_pass http://127.0.0.1:8095;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}
```

**Check logs:**
```bash
tail -f /var/log/nginx/websocket_error.log
```

### Fix 4: Test with Browser

**Open browser:**
```
https://musicassistant-app.hanold.online
```

**If web interface works:**
→ Problem is in iOS app

**If web interface doesn't work:**
→ Problem is server/proxy configuration

## iOS-Specific Issues

### Issue: App Timeout

**Cause:** iOS background timeout (30 seconds)

**Solution:**
Server must respond quickly. Check:
- Music Assistant not overloaded
- Database queries fast
- Network latency low

### Issue: App Suspension

**Cause:** App goes to background

**Solution:**
- App reconnects automatically
- Pull to refresh when returning

### Issue: SSL Certificate

**Cause:** Self-signed certificate

**Solution:**
Add ATS exception (see HTTPS-Troubleshooting.md)

## Still Not Working?

**Collect this info:**

1. **Server URL:** ________________
2. **Music Assistant Version:** ________________
3. **Reverse Proxy:** Yes/No
4. **Console Output:** (paste logs)
5. **Connection Info Screenshot**
6. **Server Logs:** (paste relevant lines)

**Debug checklist:**

- [ ] Browser can access https://YOUR_SERVER
- [ ] WebSocket test with websocat works
- [ ] Server logs show WebSocket connections
- [ ] Token is valid (not expired/revoked)
- [ ] Reverse proxy has WebSocket support
- [ ] Console shows "Connected successfully"
- [ ] Music Assistant has configured players
- [ ] Network connectivity is good

**If all checks pass but still fails:**
→ Likely a bug in the app or API incompatibility
→ Check Music Assistant version is 2.7+
→ Try with official Music Assistant mobile app to compare