SOP-010: UniFi Captive Portal Troubleshooting

Version: 1.1
Created: 2026-02-12
Last Updated: 2026-03-12 (added Issue #6: JVM heap runaway)

Scope

When to Use:

• Customer reports "can't connect to WiFi hotspot"
• Phone shows "Sign in to network" but portal doesn't load
• Browser displays ERR_CONNECTION_REFUSED on guest WiFi
• Voucher system not showing login page

Not for:

• UISP service suspension (use Payment Reconnection SOP)
• Device offline/unreachable (use device troubleshooting)
• Payment/billing issues

Prerequisites

• UniFi controller access: https://unifi.karetechsolutions.com
• Credentials: Infisical /credentials/unifi/

Common Issues

Issue 1: allowed_subnet_1 Blocking Portal Access (Most Common)

Symptoms: Phone connects, "Sign in to network" appears, but browser shows ERR_CONNECTION_REFUSED.

Root Cause: Setting allowed_subnet_1 to controller hostname creates a whitelist that can block portal access on certain network configurations.

Diagnosis:

curl -s -k -b /tmp/unifi-cookies.txt \
  "https://unifi.karetechsolutions.com/proxy/network/api/s/{SITE_ID}/rest/setting/guest_access" | \
  jq '.data[] | {allowed_subnet_1, portal_enabled, redirect_https}'

Expected good output: "allowed_subnet_1": null

Solution:

curl -s -k -b /tmp/unifi-cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -X PUT \
  "https://unifi.karetechsolutions.com/proxy/network/api/s/{SITE_ID}/rest/setting/guest_access/{SETTING_ID}" \
  -d '{"allowed_subnet_1":""}'

Via Web UI: Settings → Guest Control → Pre-Authorization Access → Remove all entries.

Issue 2: Portal HTTPS Port Not Listening (8843)

Symptoms: HTTP portal works (8880), HTTPS portal doesn't work (8843).

Diagnosis:

netstat -tlnp | grep -E "8843|8880"
# Expected: tcp6  0  0  :::8843  :::*  LISTEN

Solution:

sudo systemctl restart uosserver
# Wait 2-3 minutes

Issue 3: Access Point Offline

Diagnosis:

curl -s -k -b /tmp/unifi-cookies.txt \
  "https://unifi.karetechsolutions.com/proxy/network/api/s/{SITE_ID}/stat/device" | \
  jq '.data[] | {name, state, adopted, uptime}'

State codes: 0 = Offline, 1 = Connected, 5 = Provisioning.

Issue 4: Guest Portal Disabled

Diagnosis:

curl -s -k -b /tmp/unifi-cookies.txt \
  "https://unifi.karetechsolutions.com/proxy/network/api/s/{SITE_ID}/rest/setting/guest_access" | \
  jq '.data[] | {portal_enabled, auth, voucher_enabled}'

Expected: portal_enabled: true, auth: "hotspot", voucher_enabled: true.

Issue 5: WLAN Not Configured as Guest

Expected WLAN config: is_guest: true, security: "open", enabled: true.

Via UI: WiFi → Select SSID → Enable "Guest Network" → Set Security to "Open".

Issue 6: UniFi OS Controller Crashes (JVM Heap Runaway)

Symptoms:

• Controller inaccessible at https://unifi.karetechsolutions.com
• systemctl status uosserver.service shows restart loop
• "Container did not start within 60 seconds" in logs

Root Cause (2026-03-12): Default UniFi OS sets -XX:MaxRAMPercentage=80.0, allowing JVM heap to balloon to 6+ GB on a server with 7.7 GB RAM and 43+ containers, triggering SIGABRT via -XX:+CrashOnOutOfMemoryError.

Permanent Fix: /var/lib/unifi/env-overrides (persistent volume) hard-caps heap at 1 GB:

ENVOVERRIDES="/home/uosserver/.local/share/containers/storage/volumes/uosserver_var_lib_unifi/_data/env-overrides"
sudo python3 -c "
content = '''UNIFI_JVM_OPTS=\"-Dunifi-os.server=true -Dorg.xerial.snappy.tempdir=/usr/lib/unifi/run -XX:+UseG1GC -Xmx1024M -Xss1024K -XX:-TieredCompilation\"
'''
with open('$ENVOVERRIDES', 'w') as f:
    f.write(content)
"
sudo chown 232068:232068 "$ENVOVERRIDES"
sudo chmod 644 "$ENVOVERRIDES"
sudo systemctl restart uosserver.service

Verify:

ps aux | grep ace.jar | tr ' ' '\n' | grep -e Xmx -e MaxRAM
# Should show: -Xmx1024M
# Should NOT show: MaxRAMPercentage

Important: UniFi OS is a Podman container, NOT Docker. Use systemctl status uosserver.service, not docker ps.

Bulk Site Audit

Check all sites for allowed_subnet_1 issue:

curl -s -k -b /tmp/unifi-cookies.txt \
  "https://unifi.karetechsolutions.com/proxy/network/api/self/sites" | \
  jq -r '.data[] | "\(.name)|\(.desc)"' | \
while IFS='|' read -r site_id site_desc; do
  result=$(curl -s -k -b /tmp/unifi-cookies.txt \
    "https://unifi.karetechsolutions.com/proxy/network/api/s/$site_id/rest/setting/guest_access" 2>/dev/null | \
    jq -r '.data[]?.allowed_subnet_1 // empty' 2>/dev/null)
  if [ ! -z "$result" ] && [ "$result" != "null" ]; then
    echo "$site_desc|$site_id|$result"
  fi
done

Bulk cleanup of 71 sites was performed on 2026-02-12 in 50 seconds.

Prevention

1. Never set allowed_subnet_1 unless absolutely required
2. Audit sites monthly for this setting
3. Test portal after SSL certificate renewals
4. Monitor UniFi OS port status (8843, 8880)