← Back to Docs

Troubleshooting

Port 53 Already in Use

The most common install issue on Ubuntu 22.04+ and Debian 12+. Check what is using it:

sudo ss -lntu | grep :53

If systemd-resolved is listed:

sudo systemctl stop systemd-resolved
sudo systemctl disable systemd-resolved
sudo systemctl restart tlsops

Dashboard Not Loading

  1. Verify the service is healthy: curl http://localhost:8080/health should return {"status":"Healthy"}
  2. Check service status: sudo systemctl status tlsops
  3. Check logs: sudo journalctl -u tlsops -n 100
  4. Ensure port 8080 is not blocked: sudo ufw status or sudo iptables -L -n | grep 8080

DNS-Only Mode — Routing Policy Has No Effect

If you pointed devices at TLSOps for DNS but did not change the default gateway, TLSOps will block and filter DNS but routing policy (per-device VPN, domain routes) will not apply to actual traffic. Set the TLSOps machine as the default gateway in your DHCP server to enable full routing enforcement.

VPN Tunnel Not Connecting

  1. Confirm the WireGuard config is valid — verify the private key, public key, endpoint address and port, and allowed IPs
  2. Check that UDP can reach the provider endpoint: nc -zu <endpoint> <port>
  3. Check the Logs tab in the dashboard for sing-box errors
  4. Check sing-box logs: sudo journalctl -u tlsops -n 200 | grep -i wireguard

Devices Not Appearing in the Device List

  • TLSOps discovers devices from DNS queries and ARP — both require traffic to flow through the appliance
  • Devices with static DNS pointing elsewhere will not appear until DNS is redirected to TLSOps
  • Devices connected through the built-in WireGuard server appear automatically after their first DNS query

Content Filtering Not Working on a Device

  1. Confirm the device uses TLSOps as its DNS server: run nslookup example.com <tlsops-ip> — a response should come from the TLSOps IP
  2. TLSOps already rejects common encrypted-DNS bypass paths such as UDP 443 and TCP or UDP 853. If an app is pinned to a known HTTPS resolver domain, add a DNS rewrite for that resolver domain if needed
  3. Verify the relevant policy controls in the dashboard: global Blocklists and global Blocked Domains for network-wide filtering, plus the device's DNS Filtering, Blocked Services, and Blocked Domains settings for per-device rules

License Validation Failing

  1. Confirm the appliance has outbound internet access
  2. Open Settings and check the Access & License card — re-enter and activate your key if it shows as expired or inactive
  3. If a hardware binding mismatch is reported after moving to new hardware without a backup restore, contact support
  4. If the license shows as valid but features are still locked, reload the dashboard

Appliance Dropped to Free Plan Limits After an Update

Self-update reboots the management plane. On restart, the appliance re-validates the cached license with the server. If the licensing server was unreachable at that moment and the locally cached validation had expired (older than 5 days), the appliance temporarily falls back to Free limits. It will automatically re-validate and restore plan features once connectivity is confirmed — this typically resolves within a few minutes without any action needed.