Skip to content

Troubleshooting

Jump to bottom
KamalMac edited this page May 4, 2026 · 2 revisions

Troubleshooting

فارسی: عیب‌یابی

KevinNet App

macOS: "damaged and can't be opened" or "cannot be verified"

chmod +x KevinNet_macOS_Universal
xattr -d com.apple.quarantine KevinNet_macOS_Universal

Or right-click the app → Open → Open.

Linux: "Permission denied" when launching

chmod +x KevinNet_Linux_x64
./KevinNet_Linux_x64

Windows: antivirus blocks the app

PyInstaller-compiled apps trigger some antivirus scanners (false positive). Add an exception for the file, or build from source yourself — see BUILD_INSTRUCTIONS.txt.

VPN Binary Missing from Folder

MasterDnsVPN not in folder

The MasterDnsVPN binary must be placed next to the KevinNet app before saving. KevinNet copies it automatically.

Download links:

Platform Link
Windows AMD64 MasterDnsVPN_Client_Windows_AMD64.zip
Windows ARM64 MasterDnsVPN_Client_Windows_ARM64.zip
macOS Apple Silicon MasterDnsVPN_Client_MacOS_ARM64.zip
macOS Intel MasterDnsVPN_Client_MacOS_AMD64.zip

Steps:

  1. Extract the ZIP
  2. Rename the binary to MasterDnsVPN (macOS/Linux) or MasterDnsVPN.exe (Windows)
  3. Place next to the KevinNet app
  4. Click Save again

vaydns-client not in folder

Download from VayDNS releases. Place next to KevinNet app — any filename starting with vaydns-client is accepted:

Platform Filename
macOS Apple Silicon vaydns-client-darwin-arm64
macOS Intel vaydns-client-darwin-amd64
Linux x64 vaydns-client-linux-amd64
Linux ARM64 vaydns-client-linux-arm64
Windows x64 vaydns-client_windows_amd64.exe

macOS: binary is there but won't run

chmod +x /path/to/Iran/MasterDnsVPN
xattr -d com.apple.quarantine /path/to/Iran/MasterDnsVPN

Same for vaydns-client:

chmod +x /path/to/Iran/vaydns-client-darwin-arm64
xattr -d com.apple.quarantine /path/to/Iran/vaydns-client-darwin-arm64

Scan Finds Few or No Resolvers

Finding 0–5 resolvers:

  • Increase Pool ×1000 from 200 to 500
  • Run the scan 2–3 times — each run tests different random IPs
  • Lower Timeout to 2s if the scan is taking very long

Phase 3 (E2E) passes zero resolvers:

  • Server may be down — check it is running
  • DNS may not have propagated yet — wait up to 48 hours after creating NS records
  • Verify DNS: dig v.yourdomain.com NS
  • Wrong key — double-check against encrypt_key.txt on server

VPN Connects but Internet Doesn't Work

Browser shows no internet after connecting:

  • Set browser proxy to SOCKS5 127.0.0.1:18000 (MasterDNS) or SOCKS5 127.0.0.1:7000 (VayDNS)
  • Use a proxy extension like Proxy SwitchyOmega
  • Check that the VPN terminal window is still open

Slow Speed

MasterDNS — reduce MTU:

  • Set Max Upload MTU to 60–80
  • Set Max Download MTU to 600
  • Save and reconnect

VayDNS — try:

  • Lower Max QNAME Length to 80
  • Change Record Type to null
  • Re-scan for fresh resolvers

MasterDNS: "parse TOML failed"

The config file has an unfilled placeholder. This happens if the file was not generated through KevinNet.

Fix:

  1. Delete the country folder
  2. Go to MasterDNS Profiles tab
  3. Select the profile → click 💾 Save Changes
  4. Click 🚀 Launch VPN

MasterDNS: Frequent Disconnections

  • Increase Packet Duplication to 3
  • Change Balancing Strategy to 3 — Least Loss
  • Re-scan to get fresh resolvers — old ones may have been blocked

VayDNS: "noise handshake: timeout"

The resolver is returning NXDOMAIN — it can't reach your tunnel server. The script will try the next resolver after Resolver Timeout seconds. If all fail:

  • Check server is running
  • Verify NS delegation: dig t.yourdomain.com NS
  • Increase Resolver Timeout to 90s

VayDNS: Process Keeps Running After Ctrl+C

Re-save the profile from the VayDNS Profiles tab to regenerate the launch script with the updated trap handler.

VayDNS: "all resolvers exhausted"

All scanned resolvers failed:

  1. Re-scan — Iranian DNS servers change frequently
  2. Enter a well-known resolver: 8.8.8.8:53 in the Resolver field
  3. Check server and DNS delegation

VayDNS: NXDOMAIN when testing outside Iran

This is expected. The scanned resolvers are Iranian public DNS servers. They only forward queries for your tunnel domain when accessed from inside Iran. Testing from Australia, Europe, or anywhere outside Iran will always show NXDOMAIN.

DNS Not Propagating

dig v.yourdomain.com NS shows nothing → DNS still propagating. Can take up to 48 hours.

Also verify:

  • NS record value exactly matches the A record name (e.g. ns.example.com)
  • Cloudflare A record is DNS only (grey cloud), not proxied

Linux: Persian Text Garbled (Unjoined Letters, Wrong Direction)

v3.1.1 and later: KevinNet automatically installs the Vazirmatn font and applies proper Arabic shaping on startup. No manual action needed.

If you are on an older version or the auto-install fails:

Ubuntu / Debian:

sudo apt install fonts-vazirmatn

Fedora / RHEL:

sudo dnf install vazirmatn-fonts

Arch:

sudo pacman -S ttf-vazirmatn

After installing, restart KevinNet.

Still stuck?

Open an issue on GitHub with:

  • Your OS and KevinNet version
  • Which VPN engine (MasterDNS or VayDNS)
  • What happens when you scan (Phase 1/2/3 counts)
  • Any error messages

Clone this wiki locally