MobileMusicAssistant/Mobile Music Assistant/DocsDomain-Troubleshooting.md

Troubleshooting: musicassistant-app.hanold.online

Problem Analysis

When connecting to https://musicassistant-app.hanold.online, you're getting an NSURLErrorDomain error. This typically indicates:

1. DNS Resolution Failed - Domain cannot be resolved to an IP
2. Server Not Reachable - Domain exists but server is offline/unreachable
3. Firewall/Network Blocking - Network is blocking the connection
4. Port Not Open - Port 8095 might not be accessible from the internet

Diagnostic Steps

1. Verify Domain Resolution

On Mac/Linux:

# Check if domain resolves
nslookup musicassistant-app.hanold.online

# Check connectivity
ping musicassistant-app.hanold.online

# Test HTTPS connection
curl -v https://musicassistant-app.hanold.online:8095

# Test specific endpoint
curl -v https://musicassistant-app.hanold.online:8095/api/auth/login

Expected results:

• nslookup should return an IP address
• ping should show responses (if ICMP is allowed)
• curl should connect (even if it returns auth error)

2. Check Common Issues

Issue A: Domain Not Configured

Symptoms: nslookup fails or returns NXDOMAIN

Solutions:

• Verify DNS A record exists for musicassistant-app.hanold.online
• Wait for DNS propagation (can take 24-48 hours)
• Try using IP address directly: https://YOUR_IP:8095

Issue B: Port Not Open

Symptoms: Domain resolves but connection times out

Solutions:

• Check firewall allows port 8095
• Verify router port forwarding is configured
• Test with telnet YOUR_IP 8095 or nc -zv YOUR_IP 8095

Issue C: SSL Certificate Issues

Symptoms: Connection fails with SSL error

Solutions:

• Verify SSL certificate is valid: openssl s_client -connect musicassistant-app.hanold.online:8095
• Ensure certificate matches domain name
• Check certificate is not expired

Issue D: Music Assistant Not Running

Symptoms: Domain resolves but no response

Solutions:

• Check Music Assistant is running: systemctl status music-assistant
• Verify it's listening on all interfaces (0.0.0.0)
• Check Music Assistant logs for errors

3. Test from Different Networks

Try connecting from:

• Mobile Data (not WiFi) - Tests if home network is the issue
• Another WiFi Network - Tests if ISP is blocking
• VPN - Tests if geographic restrictions apply

4. Check Music Assistant Configuration

Music Assistant needs to be configured for external access:

config.yaml should have:

server:
  host: 0.0.0.0  # Listen on all interfaces
  port: 8095
  ssl_certificate: /path/to/cert.pem
  ssl_key: /path/to/key.pem

5. Verify Network Path

# Trace route to server
traceroute musicassistant-app.hanold.online

# Check if specific port is reachable
telnet musicassistant-app.hanold.online 8095

Common Error Codes

Error Code	Meaning	Solution
-1003	Cannot find host	DNS not resolving - check domain configuration
-1004	Cannot connect to host	Server unreachable - check firewall/port
-1001	Request timed out	Server not responding - check Music Assistant is running
-1200	Secure connection failed	SSL/TLS error - check certificate
-1009	Not connected to internet	Check device network connection

Quick Fixes

Fix 1: Use IP Address Instead

If DNS is the issue:

https://YOUR_PUBLIC_IP:8095

Fix 2: Use Local Access

If on same network:

http://LOCAL_IP:8095  (e.g., http://192.168.1.100:8095)

Fix 3: Test with HTTP First

Rule out SSL issues:

http://musicassistant-app.hanold.online:8095

⚠️ Only for testing! Use HTTPS in production.

Fix 4: Check Port in URL

Ensure you're including the port:

• ✅ https://musicassistant-app.hanold.online:8095
• ❌ https://musicassistant-app.hanold.online (will try port 443)

App-Side Improvements

The app now provides better error messages:

// DNS lookup failed
"DNS lookup failed. Cannot resolve domain name. Check the URL."

// Cannot connect
"Cannot connect to server. The server might be offline or unreachable."

// Timeout
"Connection timed out. The server is taking too long to respond."

These messages will appear in the login error alert.

Recommended Setup

For external access to Music Assistant:

Option 1: Direct Access (Simple but less secure)

1. Configure router port forwarding: External 8095 → Internal 8095
2. Set up Dynamic DNS (if you don't have static IP)
3. Configure SSL certificate for domain
4. Allow port 8095 in firewall

Option 2: Reverse Proxy (Recommended)

1. Use nginx/Caddy as reverse proxy
2. Proxy HTTPS traffic to Music Assistant
3. Let reverse proxy handle SSL
4. Use standard HTTPS port 443

Example nginx config:

server {
    listen 443 ssl;
    server_name musicassistant-app.hanold.online;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://localhost:8095;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

Option 3: Tailscale/WireGuard VPN (Most Secure)

1. Set up Tailscale or WireGuard
2. Access Music Assistant via VPN
3. No port forwarding needed
4. Fully encrypted end-to-end

Testing Checklist

• Domain resolves in DNS lookup
• Server responds to ping (if enabled)
• Port 8095 is open and accessible
• Music Assistant is running
• SSL certificate is valid
• Firewall allows connections
• Can access via web browser
• WebSocket connections work

If Still Not Working

1. Check Music Assistant logs on the server
2. Enable debug logging in the iOS app (check Xcode console)
3. Try from web browser first to isolate app issues
4. Verify with curl to test raw HTTP connection
5. Check router logs for blocked connections

Contact Information

If you've verified all the above and it still doesn't work, the issue is likely:

• Server-side configuration - Check Music Assistant setup
• Network infrastructure - Check router/firewall
• DNS configuration - Verify domain points to correct IP