Troubleshooting

Quick Diagnostics

# Check connection and nodes
baseguard status

# Verify daemon is running
sudo systemctl status baseguard    # Linux
sudo launchctl list | grep baseguard  # macOS

# Test connectivity to another node
ping 100.64.0.5
nc -zv 100.64.0.5 22

Installation & Daemon Issues

Daemon not running

Start the daemon manually:

TUN device not available (Linux)

Minimal or container environments may need the TUN kernel module enabled:

sudo modprobe tun

Connection & Network Issues

Can't connect at all

1. Ensure daemon is running (see above)
2. Verify HTTPS (443) outbound is allowed — required for control plane
3. Verify DNS resolves the control plane hostname
4. Check firewall allows outbound UDP on port 42273 — required for WireGuard

Can't see other nodes

• Confirm other devices are connected (baseguard status on those devices)
• Check ACL rules allow traffic between them
• Verify you're in the same organization

All connections using relay

Relay means P2P failed. Common causes:

# Open UDP port (Linux)
sudo ufw allow 42273/udp

# Force reconnection to retry P2P
baseguard disconnect && baseguard connect

DNS Issues

Node names don't resolve

1. Ensure DNS is enabled in Settings > DNS — the DNS navigation entry is hidden while it is off
2. Ensure DNS is not disabled locally: baseguard set should print dns: true (see baseguard set)
3. Verify Baseguard is connected with baseguard status and that the target node is listed — only nodes you are allowed to reach under your network rules are resolvable
4. Try the overlay IP directly to isolate DNS from connectivity issues
5. Query the node resolver directly to bypass the system configuration: dig @100.64.0.1 server-01.<your-domain> (use the first address of your organization's IPv4 range)

Short names work but the full name doesn't (or vice versa)

• Short names (ping server-01) rely on the organization domain being present as a search domain. Some applications bypass search domains; use the full name server-01.<your-domain> instead.
• On Linux with systemd-resolved, check resolvectl status and confirm the Baseguard tunnel interface lists your domain and the node resolver.

Internal domain not routed to my nameserver (split DNS)

1. Confirm the nameserver's Match Domain is the suffix of the name you are resolving (e.g. corp.example.com for db.corp.example.com)
2. Check the nameserver's Tags — an entry with tags applies only to nodes carrying at least one of them
3. Make sure the nameserver's address is reachable from the node (for an internal resolver, it usually needs to be on the mesh and allowed by your network rules)
4. Split-DNS queries never fall back to other resolvers; if the matched nameserver is down, the query fails

External DNS broken after enabling Baseguard DNS

1. If you configured global nameservers (no match domain), confirm they are reachable from the node's network — some corporate networks block outbound port 53 to public resolvers
2. Turn off Override local DNS in Settings > DNS to let nodes fall back to their own system resolvers when all global nameservers fail
3. Remove the global nameservers to return to the node's system resolvers, or disable DNS on the affected node with baseguard set --dns=false

Windows: queries leak to other adapters

Baseguard adds a Name Resolution Policy Table (NRPT) rule so all queries reach the node resolver. Windows ignores local NRPT rules when Group Policy NRPT rules are present — check Get-DnsClientNrptPolicy in PowerShell. Windows 10 build 19041 or later is required.

Update Issues

Node doesn't auto-update

1. Check Settings > General > Auto Update is enabled and note the Maintenance Window — it is a one-hour window in UTC, so the node may simply be waiting for it
2. The node must be connected during the window; offline nodes update at the next window after they reconnect
3. Run baseguard update on the device to update immediately and see any error
4. Mobile apps are not auto-updated; use the app store

baseguard update says "Baseguard network is down"

Updates are performed by the daemon and require an active connection. Run baseguard connect first.

baseguard update says an update was started recently

A 5-minute cooldown applies after each update attempt. Wait a few minutes and retry. Check the daemon logs if the version did not change — the most common causes are blocked access to github.com (downloads come from GitHub Releases) or a failed signature verification, in which case nothing is installed.

Authentication & Login Issues

Authorization URL doesn't open

Copy the URL manually and paste it into your browser.

Authorization times out

• Check your internet connection
• Ensure you're logged into the console
• Try again with baseguard login

Auth key rejected

• Verify the key is copied correctly (no trailing spaces)
• Check key hasn't expired or been revoked
• Ensure key hasn't reached its usage limit (single-use keys)
• Create a new auth key if needed

Device rejected

• Check if node approval is enabled — your device may be waiting for admin approval
• Verify user has organization membership

Credential problems

baseguard logout
baseguard login

Organization Issues

"Organization not found" or not listed

# List your organizations
baseguard organizations

# Use the correct ID
baseguard connect --org-id <correct-id>

If no organizations appear, re-login with baseguard login to refresh. If still empty, contact your organization admin for access.

Access Control Issues

Traffic blocked unexpectedly

1. Verify source and destination nodes have the expected tags
2. Check ACL rules cover the protocol and port
3. Test from the source node:

nc -zv <overlay-ip> <port>    # TCP
ping <overlay-ip>              # ICMP

Traffic allowed unexpectedly

1. Look for rules with empty tags (matches all nodes)
2. Review all ACLs — any matching rule permits traffic, regardless of order

Tags not applied from auth key

1. Verify tags are configured on the auth key
2. Check the tags exist in the organization

API Issues

See API Reference for authentication details.

Getting Help

If you can't resolve an issue, contact support.

See Also

• FAQ — Frequently asked questions
• CLI Reference — Command-line interface