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:**
```bash
# 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:**
```yaml
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

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

```swift
// 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:**
```nginx
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