Troubleshooting and FAQ

Troubleshooting and FAQ

Troubleshooting

"V2Mac can't be opened" / "Apple could not verify…" The DMG is not notarized. Click Open Anyway in System Settings → Privacy & Security, run xattr -dr com.apple.quarantine /Applications/V2Mac.app, or install with Homebrew.

Connected, but nothing loads ("No answer through this server") The core runs but the server does not pass traffic. Test the group's real delay (⌘T) and pick a server that answers, or turn on automatic server selection. Check the log panel (⇧⌘L) for the core's error. On filtered networks, click Find Settings… under TLS fragment in Settings → Connection, and for servers behind Cloudflare try Find Clean IP.

"Port 10808 is in use" Another app (or another proxy client) holds the port. The notification offers Use Port N, or change the port in Settings → Proxy.

A server fails with "unknown authority" It uses a self-signed certificate. Turn on Allow insecure servers in Settings → Connection only if you trust the server.

The core does not start after I added a rule A geosite: or geoip: list in a rule does not exist. The log names it. Remove or fix the rule; the Rules window only offers lists that exist.

App rules have no effect In TUN mode apps are not identified; use host or IP rules. Without TUN, an app must use the system proxy or V2Mac's port. With System Proxy off, apps you pointed at the port yourself skip the rules.

Browser ignores host rules Browsers use QUIC (UDP 443), which hides the host name. Turn on Block QUIC in the Rules window.

No internet after V2Mac quit or crashed The kill switch keeps blocking until V2Mac lifts it. Open V2Mac and click Allow Traffic, or restart the Mac.

The system proxy dot is red Another app changed the system proxy settings. Turn System Proxy off and on again.

TUN asks for my password every time Ad-hoc builds (DMG, Homebrew) ask once per app session. Apple-signed builds use a helper you approve once.

Subscription update fails Try the other route (Update via Proxy while connected). Clash YAML and sing-box subscriptions work; if one reports no servers, its servers are of a kind V2Mac cannot use (TUIC, WireGuard).

Reporting a bug Open an issue with your macOS version, V2Mac version (Settings → About) and the log (Copy All in the log panel). Remove server addresses and keys first. If V2Mac crashed, also attach the newest V2Mac or xray .ips file from Settings → General → Show Crash Reports.

FAQ

Is V2Mac a V2Ray client for Mac? Yes. It runs Xray-core, the successor of V2Ray core, and reads V2Ray and Xray links and subscriptions.

Does it support VLESS REALITY and XTLS Vision? Yes, from links and in the server editor, with TCP, WebSocket, gRPC, HTTPUpgrade, XHTTP and mKCP transports.

How do I proxy all apps, including ones without proxy settings? Turn on TUN.

Can I use it as a Proxifier replacement? Yes. Rules by app and host, import from Proxifier, Clash, sing-box, v2rayN and Shadowrocket, and Block QUIC. See Routing.

Can other devices on my network use it? Yes: Settings → Proxy → Allow connections from LAN, ideally with a username and password. Point the other device at your Mac's LAN address and port.

Does it work on Intel Macs or older macOS? No. It needs macOS 26 or later on Apple Silicon.

Does V2Mac collect data? No. See Settings Reference.

How do I stop WebRTC and DNS leaks in Chrome? Use noleaker, a free extension from the same author, with proxy 127.0.0.1:10808.

Where are my servers stored, and how do I move them to another Mac? In ~/Library/Application Support/v2mac. Use Export Backup… and Restore Backup….