MobileMusicAssistant/Mobile Music Assistant/DocsHTTPS-Troubleshooting.md

HTTPS Connection Issues - Troubleshooting Guide

Problem: Login doesn't work via HTTPS

If you're experiencing connection issues when using HTTPS (e.g., https://192.168.1.100:8095), it's likely due to App Transport Security (ATS) blocking the connection.

Quick Fix: Enable App Transport Security Exceptions

Option 1: Allow All Insecure Loads (Development Only)

⚠️ WARNING: Only use this for development/testing! Never in production!

Add to your Info.plist:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

How to add in Xcode:

1. Select your target → Info tab
2. Hover over any row and click the "+" button
3. Type "App Transport Security Settings"
4. Click the disclosure triangle to expand
5. Add a row inside: "Allow Arbitrary Loads" = YES

Option 2: Allow Specific Domain (Safer)

If you know your server's domain/IP:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSExceptionDomains</key>
    <dict>
        <key>192.168.1.100</key>
        <dict>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <true/>
            <key>NSIncludesSubdomains</key>
            <true/>
        </dict>
    </dict>
</dict>

Why Does This Happen?

1. Self-Signed Certificates: Most local Music Assistant servers use self-signed SSL certificates
2. ATS Requirements: iOS requires valid certificates from trusted Certificate Authorities
3. IP Addresses: HTTPS with IP addresses (not domains) often fails certificate validation

What Was Fixed in Code:

✅ Better error logging in MAAuthManager.login() ✅ Proper HTTP status code handling (200, 401, etc.) ✅ Detailed error messages in console ✅ Timeout configuration for slow networks

Check the Console for Errors

When login fails, check Xcode console for messages like:

[ERROR] Login failed with status 401
[ERROR] Login network error: The certificate for this server is invalid
[ERROR] NSURLSession/NSURLConnection HTTP load failed (kCFStreamErrorDomainSSL, -9802)

These indicate ATS is blocking the connection.

Production Solution

For production apps, you should:

1. Get a valid SSL certificate (Let's Encrypt, etc.)
2. Use a proper domain instead of IP address
3. Configure DNS to point to your server
4. Remove ATS exceptions from Info.plist

Testing HTTPS

To verify your HTTPS connection works:

1. In Safari: Visit https://YOUR_SERVER:8095

   • If you see a certificate warning, that's the issue

2. In Terminal:

   curl -v https://YOUR_SERVER:8095/api/auth/login
   

   • Check for SSL errors

3. Check Server Logs: Music Assistant should log connection attempts

Alternative: Use HTTP Instead

For local network use, HTTP is fine:

• Use http://192.168.1.100:8095
• No certificate issues
• Still secure on your local network
• ATS allows localhost/local IP HTTP connections

Complete Info.plist with ATS Exception

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <!-- ... other keys ... -->
    
    <!-- Background Audio -->
    <key>UIBackgroundModes</key>
    <array>
        <string>audio</string>
    </array>
    
    <!-- App Transport Security (for self-signed HTTPS) -->
    <key>NSAppTransportSecurity</key>
    <dict>
        <key>NSAllowsArbitraryLoads</key>
        <true/>
    </dict>
</dict>
</plist>

Summary

Problem: iOS blocks HTTPS connections to servers with invalid/self-signed certificates

Solution: Add ATS exception to Info.plist

Best Practice: Use HTTP for local servers, HTTPS with valid certificates for production