Troubleshooting
Common issues
Start with the basic connectivity checks. Most problems are either networking (TrueNAS not reachable) or TLS (certificate changed).
Agent Web UI not reachable
- Check the published port mapping (example:
18080 → 8080).
- Confirm the container is running and restarting is not looping.
- Make sure your browser reaches the correct host/IP of the Agent.
Pairing fails
- Generate a new pairing code in the iOS app (codes are meant to be short-lived).
- Make sure the Agent can reach the internet to fetch the pairing config (if your setup uses a push/config server).
- Try again and watch the Agent UI for error messages.
No alerts / Agent shows disconnected
- Verify the TrueNAS URL the Agent uses is reachable from the Agent network.
- If you use a hostname, test with a resolvable DNS name or use an IP address.
- Confirm the TrueNAS API key is valid.
Tip: Hostnames that work on your laptop may not resolve inside containers.
TLS errors / pinned certificate mismatch
If the TrueNAS certificate changed, the Agent may reject the connection because the pinned fingerprint no longer matches.
- Confirm you are connecting to the correct TrueNAS system (correct IP/host).
- If the certificate was intentionally changed, use Reset certificate pin in the Agent UI.
- After resetting, reconnect so the Agent can pin the new certificate.
Security: Do not reset the pin if you cannot explain why the certificate changed.