Running Into Issues? Find Answers Here
These are organized by "symptom" for the most common issues, so you don't need to read a full tutorial — just find the matching problem.
New here and haven't gotten started yet? Check out the Beginner Tutorial.
Connected, but Something Feels Off
Shows connected but pages won't load, or speed suddenly drops — these are the most common causes.
Shows "Connected" but Web Pages Still Won't Load?
First check the current node's latency: if it's timing out or shown in red, switch to a node with normal latency and try again. If latency looks fine but pages still won't load, check whether the proxy mode has accidentally switched to "Direct"; on desktop, you can also open the "Logs" page to see exactly which connection is being rejected and why. In rare cases, it's a DNS resolution glitch — restarting the core usually fixes it.
Internet Noticeably Slower with the Proxy On?
First rule out node issues: switch to the "Auto Select" group so it automatically picks the lowest-latency route. If every node is slow, it may be peak-hour congestion on your provider's lines — try a different time of day or contact your provider. Also check whether "Global mode" got turned on by mistake, routing all traffic through the proxy indiscriminately; switching back to "Rule mode" restores full speed for direct-connection traffic.
Only Some Sites Won't Load, Others Work Fine?
This usually means a routing rule is incorrectly sending that site through direct connection. Open the "Rules" page and search for the domain to see which rule it matches; if the rule set itself looks fine, it's likely DNS pollution. Check the DNS Configuration section in the docs, and confirm fake-ip and fallback are set to the recommended values.
Node Latency Always Shows Timeout or a Squiggly Line?
First manually click "Test Latency" once to rule out a stale display. If it still times out, the node is likely down or your subscription has expired — check your account status with your provider. If only a few nodes are affected, just switch nodes instead of repeatedly retrying a broken one.
Common Subscription Link Pitfalls
Failed updates, empty imports, whether it works on a new device — these are the most common snags with subscriptions.
Clicking "Update" on Your Subscription Keeps Failing or Spinning Forever?
First confirm the subscription URL itself is reachable: paste it into your browser — if it won't load, the URL is blocked or your provider is having issues, so try updating over mobile data instead. If the link loads fine but the client still fails to update, check that your system clock is accurate (a large time discrepancy can break certificate validation); the update timeout might also be too short, so try retrying manually from the "Profiles" page.
Switched to a New Device — Does My Old Subscription Link Still Work?
Yes. The subscription link itself isn't tied to any device — as long as you haven't exceeded your provider's device limit, just paste the same link into your new device to import it, and you'll get the exact same nodes. It's recommended to manually hit "Update" once after switching devices to make sure you have the latest node list.
My Provider Says the Subscription Is Fine, but Importing Gives Me Nothing?
This is most often caused by missing characters at the end when copying the link — copy it again in full to be safe. Also check for stray spaces or line breaks that snuck into the input field. If the link is confirmed correct, try deleting the old profile and adding it fresh, rather than repeatedly clicking update on the existing one.
Can't Install, Won't Open, or Gets Blocked
Usually a system security mechanism or software conflict, not a problem with the installer itself.
macOS Says "File Is Damaged" or "Can't Verify Developer" and Won't Open?
This is macOS Gatekeeper's default block on unsigned apps — it doesn't mean the file is actually damaged. Go to "System Settings → Privacy & Security", scroll down to the notice about the blocked app, and click "Open Anyway". On some older macOS versions, you'll instead need to Control-click the app icon, choose "Open", and confirm once more in the pop-up.
Antivirus on Windows Flags or Blocks the Install?
Proxy tools modify system network settings, which often trigger false positives from heuristic antivirus rules — this is a well-known industry-wide issue. The source code is fully public and can be audited on GitHub. You can temporarily add the installer to your antivirus's trusted list, or grab the latest build directly from the GitHub repo.
The Client Doesn't Start Automatically on Boot?
Go to the client's "Settings" page and confirm the "Launch on startup" toggle is on; on desktop, also check whether it's been manually disabled in your system's startup manager. Windows users should additionally check if a third-party cleanup/optimizer tool has auto-disabled the startup entry — just turn it back on.
Does Running Alongside Other Proxy Tools or a VPN Cause Conflicts?
Yes. Only one tool should control the system proxy and network adapter at a time — running two at once causes them to fight over ports or the routing table, making both unstable. Before using it, fully quit any other proxy/VPN tool (not just minimize it), and when switching, always close one before opening the other.
Crashes, Freezes, and Odd Behavior
Most one-off issues have a simple self-check before you need to treat them as a bigger problem.
Client Suddenly Crashes or Shows a Blank Screen on Launch?
First try fully quitting and reopening — most one-off issues resolve with a simple restart. If it keeps happening, check your config file for YAML formatting errors from manual edits (mixed tabs and spaces is the most common cause); you can revert to a previously working config to confirm whether it's a config issue or a client issue.
Memory or CPU Usage Suddenly Spikes?
First check how many rule sets you've subscribed to — too many, or overly complex rules, increase the cost of matching each connection. Also check whether the log level was accidentally left on "debug" long-term; switching back to "info" or "warning" significantly reduces resource usage. If usage keeps climbing and never drops, a connection may be stuck in a reconnect loop — restarting the core will clear it.
Logs Are Full of Red Errors — Is Something Wrong?
Not necessarily. Individual node connection failures or single speed-test timeouts will log in red — this is normal, expected fault tolerance, and fine to ignore as long as your overall connection isn't affected. If the exact same error keeps flooding the log, look up the specific domain or node name mentioned in the error rather than trying to parse every log line.
Open an Issue on GitHub — the Maintainers Will See It
If none of the above matches your situation, describe the issue clearly (OS, version, log screenshots) and submit it on GitHub — the community usually responds quickly. For everyday config questions, you're also welcome to check the Configuration Guide or the Advanced Blog.
Go to GitHub Issues