FreeGuard CLI Troubleshooting

Running into problems with FreeGuard CLI? This guide covers the most common issues and their solutions. For every problem, try running freeguard doctor first — it automatically detects most configuration and environment issues.

Installation Issues

Permission denied during installation

Symptom: The install script fails with Permission denied or EACCES.

Solution: On macOS/Linux, the installer needs write access to /usr/local/bin. Run with elevated privileges:

curl -fsSL https://downloadcli.freeguardvpn.com/cli/install.sh | sudo sh

On Windows, make sure you open PowerShell as Administrator before running the install command.

Command not found after installation

Symptom: Running freeguard returns command not found or not recognized.

Doctor output:

✗ CLI binary:     Not in PATH

Solution: The binary may not be in your shell’s PATH. Add it manually:

# macOS/Linux — add to your shell profile (~/.bashrc, ~/.zshrc)
export PATH="$HOME/.freeguard/bin:$PATH"

# Then reload your shell
source ~/.zshrc  # or ~/.bashrc

On Windows, add %USERPROFILE%\.freeguard\bin to your system PATH environment variable and restart your terminal.

curl fails or download times out

Symptom: The install script cannot download the binary.

Solution: If you are behind a corporate firewall or in a restricted network, download the binary manually from the GitHub Releases page and place it in ~/.freeguard/bin/. Then make it executable:

chmod +x ~/.freeguard/bin/freeguard

Login Problems

Verification code not received

Symptom: After running freeguard login --email [email protected] --send-code, no email arrives.

Solution:

1. Check your spam/junk folder — verification emails sometimes get filtered.
2. Wait 2 minutes before requesting again. There is a rate limit on code sending.
3. Verify the email address is correct:

freeguard login --email [email protected] --send-code

4. Try a different email provider if the issue persists.

Token expired

Symptom: Commands fail with Authentication expired or Token invalid.

Doctor output:

✗ Credentials:     Token expired (last refresh: 2026-03-01)

Solution: Login again to refresh your credentials:

freeguard logout
freeguard login --email [email protected] --send-code

Wrong email — no subscription found

Symptom: Login succeeds but freeguard connect says No active subscription.

Doctor output:

✓ Credentials:     Logged in (email: u***@example.com)
✗ Subscription:    No active subscription found

Solution: Make sure you are logging in with the same email you used to purchase your subscription. If you used a different email:

freeguard logout
freeguard login --email [email protected] --send-code

Connection Issues

Connection timeout

Symptom: freeguard connect hangs or returns Connection timed out.

Doctor output:

✗ Network:         Internet not reachable

Solution:

1. Check your base internet connection (disconnect VPN first):

freeguard disconnect
ping 8.8.8.8

2. Try a different node or country:

freeguard connect --country SG

3. Try a different protocol that may work better on your network:

freeguard connect --protocol hysteria2

Port 7890 already in use

Symptom: freeguard connect fails with Port 7890 is already in use.

Doctor output:

✗ Port 7890:       In use by another process (PID: 12345)

Solution: Another proxy application is using the default port. Either stop the other application, or change the FreeGuard proxy port:

freeguard config set proxy.port 8080
freeguard connect

DNS leak detected

Symptom: DNS queries bypass the VPN tunnel.

Solution: Switch to a secure DNS configuration:

freeguard config set dns.provider secure
freeguard disconnect
freeguard connect

You can verify DNS is routed through the VPN:

freeguard doctor

Look for the DNS check in the output to confirm it is working correctly.

Permission Issues

TUN mode requires sudo

Symptom: freeguard connect --tun fails with Permission denied: TUN device.

Doctor output:

✗ TUN permission:  Not available (run with sudo for TUN mode)

Solution: TUN mode creates a virtual network interface, which requires elevated privileges:

# macOS/Linux
sudo freeguard connect --tun

# Windows — run PowerShell as Administrator
freeguard connect --tun

If you do not need system-wide VPN coverage, use the default system proxy mode instead (no sudo needed):

freeguard connect

Port below 1024 requires elevated privileges

Symptom: Setting a proxy port below 1024 fails with Permission denied.

Solution: Ports below 1024 are restricted on most operating systems. Use a port above 1024:

freeguard config set proxy.port 7890

Or run with elevated privileges if you specifically need a low port:

sudo freeguard connect

Still Stuck?

If freeguard doctor and the solutions above do not resolve your issue, let AI diagnose it automatically.

Visit the FreeGuard CLI Agent page and describe your problem. The agent can read your freeguard doctor --json output and walk you through a fix step by step.

You can also run the interactive troubleshooting wizard:

freeguard doctor --json | pbcopy
# Then paste the output into the CLI Agent chat

Frequently Asked Questions

Why does FreeGuard CLI say “connection refused”?

This usually means the VPN server is temporarily unavailable. Try freeguard connect --server auto to auto-select the best available server, or check your firewall settings.

How do I check if my VPN connection is working?

Run freeguard status to see your connection state, current server, and protocol. You can also run curl ifconfig.me to verify your IP address has changed.

FreeGuard CLI won’t start after system update. What should I do?

Run freeguard update to get the latest version. If that fails, reinstall with the install script: curl -fsSL https://downloadcli.freeguardvpn.com/cli/install.sh | sh.

How do I report a bug or get help?

Run freeguard debug to collect diagnostic information, then contact support via the website or email. Include the debug output for faster resolution.

Last updated: March 2026