Troubleshooting

UniFi API Auth Errors

UniFi OS (API Key)

• Use the local controller URL (e.g. https://192.168.1.1), not the Ubiquiti cloud URL.
• The site ID must be the internal name (usually default), not the display name shown in the UniFi UI.
• Use a Local AdminAPI key, not a cloud admin key. Create one in UniFi OS under Settings → Admins → Local Admin.
• If you changed SECRET_KEY or POSTGRES_PASSWORD after initial setup, stored API keys become unrecoverable. Re-enter the UniFi API key in Settings.

Self-Hosted Controller (Username/Password)

• Use a local account on the controller, not a Ubiquiti SSO account.
• The controller URL should point to the local address and port (e.g. https://192.168.1.10:8443).
• If the controller uses a self-signed certificate, set UNIFI_VERIFY_SSL=false or configure it in Settings.
• Firewall rule management is not available on self-hosted controllers. Use the UniFi controller UI to toggle syslog on individual firewall rules.

No Logs Appearing

• Confirm your UniFi gateway's syslog is pointed at the Insights Plus host on UDP port 514.
• Syslog must be enabled per firewall rulein the UniFi controller. Use the Settings → Firewall zone matrix to bulk-toggle syslog.
• Check container logs for receiver errors:

docker logs unifi-log-insight --tail 100

Verify that UDP 514 is not blocked by a host firewall or already in use by another process.

GeoIP Not Working

• Verify the .mmdb files exist in the MaxMind volume:

docker exec unifi-log-insight ls -la /app/maxmind/

• Check the health endpoint for GeoIP status:

curl http://localhost:8090/api/health

• If auto-update is configured, check the update log:

docker exec unifi-log-insight cat /var/log/geoip-update.log

• To trigger a manual update:

docker exec unifi-log-insight /app/geoip-update.sh

Container Won't Start

• Check the container logs for startup errors:

docker logs unifi-log-insight

• Verify your .env file exists and contains POSTGRES_PASSWORD.
• If the database is corrupted, reset with a full wipe (this destroys all data):

docker compose down -v

Then start fresh with docker compose up -d.

External Database Issues