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:

// 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:

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:

# 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:

# You'll need to send auth first
# This is complex - use app debugging instead

5. Test API Endpoints

Test REST API:

# 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:

# 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:

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:

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