Troubleshooting

Common issues and how to fix them.

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.

Firewall policies without an id

What you see

In Settings → Firewall, some rules have a greyed-out syslog toggle. Hovering it explains that the UniFi controller returned the rule without an id.
A yellow notice above the policy table says how many policies came back without an id, with a link to this page.
In an expanded log entry, Rule Logging says the controller returned the matching policy without an id, so its logging cannot be toggled there.
The container log has a warning that starts with Integration API returned N firewall policies without an id.

Why it happens

Insights Plus reads and changes firewall policies through the UniFi Integration API. Every change is sent to one policy, addressed by its id.
Some controllers return policies with no id at all. So far this has only been seen for legacy user-defined rules that the zone-based firewall migration did not fully convert.
A policy without an id cannot be addressed through the Integration API, so Insights Plus has nothing to send the change to.
Background and diagnostics: GitHub issue #112.

What Insights Plus does

Keeps the rule in the policy list. The gateway still enforces it.
Counts it in the zone matrix when the rule is enabled, so the Allow All, Block All and Allow Return labels stay accurate.
Disables its logging toggle and leaves it out of group and bulk toggles. No update is ever sent for it.

How to check

Set three variables first: your controller URL, an API key from a Local Admin account, and the site UUID.

export UNIFI_HOST="https://192.168.1.1"
export UNIFI_API_KEY="your_api_key"

# List sites; use the id of the site whose internalReference is "default" (or your site)
curl -sk -H "X-API-Key: $UNIFI_API_KEY" \
  "$UNIFI_HOST/proxy/network/integration/v1/sites" \
  | jq '.data[] | {id, internalReference, name}'

export SITE_UUID="paste-the-site-id-here"

Count the policies with and without an id:

curl -sk -H "X-API-Key: $UNIFI_API_KEY" \
  "$UNIFI_HOST/proxy/network/integration/v1/sites/$SITE_UUID/firewall/policies?limit=200" \
  | jq '{total: (.data | length), with_id: ([.data[] | select(.id != null)] | length), without_id: ([.data[] | select(.id == null)] | length)}'

Show the full JSON of one policy without an id:

curl -sk -H "X-API-Key: $UNIFI_API_KEY" \
  "$UNIFI_HOST/proxy/network/integration/v1/sites/$SITE_UUID/firewall/policies?limit=200" \
  | jq '[.data[] | select(.id == null)][0]'

If you have more than 200 policies, repeat with &offset=200 (and so on) until every page is covered.

How to fix it

Toggle syslog in the UniFi Network app. Open the rule in the UniFi Network app and change its syslog setting there. This works whether or not the rule has an id.
Recreate the rule. Note the rule's settings and its position in the rule order, delete it, and create it again in the UniFi Network app. The new rule gets an id, so Insights Plus can toggle it. Put it back in its original position by hand, because rule order decides which rule matches first.
Do not edit the controller database directly. It is unsupported and can break your controller.

After either change, click refresh in Settings → Firewall. The notice disappears once every policy has an id.

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

Symptom	Fix
Connection refused	Verify DB_HOST, DB_PORT, and that the PostgreSQL server allows remote connections (check pg_hba.conf and listen_addresses)
Password authentication failed	Confirm DB_PASSWORD matches the database user's password. If using POSTGRES_PASSWORD as fallback, ensure DB_PASSWORD is set explicitly for external databases
Permission denied	The DB_USER must own or have full privileges on DB_NAME. Run GRANT ALL ON DATABASE ... TO ... as superuser
SSL required	Set DB_SSLMODE=require (or verify-ca / verify-full). Provide DB_SSLROOTCERT if the server uses a private CA
Health check shows unhealthy	Check container logs with docker logs. Verify the external database is reachable from the container network and credentials are correct

Database Maintenance