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

DNS resolution fails

1. Ensure DNS is enabled in Settings > DNS
2. Verify Baseguard is connected
3. Try using the overlay IP directly to isolate DNS from connectivity issues

External DNS broken after enabling Baseguard DNS

1. Check for conflicts with system DNS configuration
2. Try disabling Baseguard DNS in Settings > DNS

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