Surge Knowledge Base
Ask or search…
Comment on page

Surge Mac FAQs

Why can only IPs be seen in TCP requests and not domain names

If you find that all TCP requests in the Dashboard are displayed as IP addresses and domain names are not shown, it means that Surge failed to hijack DNS. For a detailed explanation of the principle, please refer to: 《Surge Official Chinese Guide: Understanding Surge Principles》
Possible reasons and solutions include:
  • First, please check whether the DNS settings of the device are set to Surge's dedicated DNS address: Surge automatically modifies the DNS of the current device when Enhanced Mode is enabled, and automatically configures this DNS for client devices under DHCP mode.
  • Some operating systems or browsers support DoH/DoT or other encrypted DNS protocols, and Surge cannot hijack such DNS requests. Please manually disable this feature.
  • Other software that hijacks system DNS is installed on the device.

Requests not displayed in the request viewer

If requests are not displayed in the Surge request viewer, you can troubleshoot in the following order:
  1. 1.
    Confirm that Surge has taken over the network of the local or another device:
  • Enabling the Set as System Proxy option can take over most HTTP/HTTPS requests from the current device.
  • Enabling Enhanced Mode can take over almost all requests from the current device.
You can confirm whether the takeover was successful through the client and process list on the Surge main interface. If there are items, it means the takeover was successful.
  1. 2.
    Confirm the filter settings of the request viewer
In the Capture page of the Surge main program, you can configure the request viewer capture filter parameters. If these parameters are not configured properly, the request viewer may not display results.

How to deal with abnormal Helper

If the Surge Mac Helper is abnormal, it will cause the system proxy to not be set and Enhanced Mode cannot be turned on. (Force cleaning with CleanMyMac or other cleaning software may cause this problem)
Please follow these steps to fix:
  1. 1.
    Open Surge Mac's settings interface, select Advanced, and click Remove Helper.
  2. 2.
    Enter your system login password.
  3. 3.
    Click Open Terminal.
  4. 4.
    Enter your system login password again in the terminal window and press Enter.
  5. 5.
    Restart the computer.
  6. 6.
    Open Surge, try to check Set as System Proxy, and enter the system password to reinstall the Helper.
Since macOS is a developmental system, the causes of this problem can be very complex. If it still doesn't work, you may need to try resetting the entire system.

Using Surge Mac and VPN together

If you connect to another VPN while Surge is running, there may be problems. Try turning off Enhanced Mode. If you need to enable Enhanced Mode, you need to use a custom direct policy to force binding interface, as detailed in the manual.
If you encounter problems with domain names in the intranet not being resolved, please:
  1. 1.
    If the VPN is correctly configured with Split DNS, then the system can perform DNS resolution to get the correct result. Use the Local DNS Mapping feature to directly configure the intranet domain name to be resolved by syslib.
* = server:syslib
  1. 2.
    Please note that the server:syslib parameter will not work when Enhanced Mode is enabled. You can use the Local DNS Mapping feature to directly hand over the intranet domain name to the intranet DNS for resolution.
* = server:
If this domain name can also be accessed from the public network, such a configuration may cause problems. (You can solve this by using a DNS script to determine the environment)

Enhanced Mode compatibility issues

The principle of Surge Mac's Enhanced Mode is to take over all traffic through a virtual network card. This mode of operation may cause compatibility issues, which may manifest as slow internet speed, Surge being closed, or Surge responding slowly, etc. The following are some known programs that may cause conflicts.
  • AdGuard
  • Viscosity
  • Little Snitch

Why do I get a message saying that I can't modify various settings when I try to change them?

If your profile comes from someone else, it will automatically update with remote changes (i.e., Managed Profile).
Since remote updates can overwrite local settings at any time, you are not allowed to adjust settings locally in this case to avoid conflicts.
If you want to adjust the profile based on the original hosted profile, you can:
  1. 1.
    Create a copy of the managed profile, which will unlink the new profile from the original's automatic updates, allowing you to edit freely.
  2. 2.
    Create a Linked Profile based on that profile, referencing only certain sections (usually [Proxy] and [Proxy Group]) from the original, allowing you to edit other sections' related settings. More information: Detached Profile

Why does Surge frequently notify me of poor network quality?

Simply put, this notification appears when there is indeed a problem with the network, and the network is almost unusable.
Technically, when Surge detects that the handshake time of TCP exceeds 2000 ms, it sends a DNS request to all traditional DNS servers in the current configuration. If no response is received within 2000 ms, it determines the network quality is poor and provides a notification.
  • If this notification frequently appears when the network is actually fine, please check if the DNS server configuration is reasonable.
  • If you do not wish to receive this notification, you can turn it off individually in the notification settings within Surge.

Why does Surge block QUIC traffic when forwarding to proxies?

By default, Surge automatically decides whether to allow forwarding of QUIC/HTTP3 traffic based on the type of proxy, as most proxies are not suitable for forwarding QUIC traffic, causing serious performance issues.
Almost all applications have a mechanism to automatically fallback to HTTPS when QUIC is unavailable, so there is no need to worry about QUIC-BLOCK causing a website to be inaccessible or an app unusable.
Compared to HTTP/2, the QUIC (HTTP/3) protocol only has a slight performance improvement, and since both use TLS/1.3 as the security layer, their security is almost identical. The performance issues caused by inappropriate proxy forwarding far outweigh the improvements of HTTP/3, so there is no need to allow QUIC traffic just for the sake of using HTTP/3.
If you need to use QUIC for development and debugging purposes, adjust the QUIC Block option in the settings of the corresponding proxy policy.
Why are most proxy protocols not suitable for forwarding QUIC traffic? Both TCP and QUIC protocols are reliable transport protocols, meaning they will automatically retransmit a data packet if they detect that it is lost.
Let's look at a hypothetical situation where a TCP-based proxy forwards QUIC and see what problems arise:
  1. 1.
    Send data segment A, which is encapsulated in QUIC's UDP packet B, and then encapsulated in TCP packet C through a TCP-based proxy.
  2. 2.
    Network jitter occurs, and the C packet is lost.
  3. 3.
    TCP protocol detects the loss and retransmits packet C'2.
  4. 4.
    QUIC protocol also detects the loss and retransmits packet B'2, which appears as a new data stream in the TCP layer, generating a new TCP packet D.
As you can see, a single packet loss leads to double retransmissions in the nested reliable transport protocols. This is a simple example; severe packet loss would lead to a large number of retransmissions at the QUIC layer. The TCP layer then ensures all QUIC layer retransmissions are delivered (even though they contain the same data), causing congestion to exponentially rise.
This only touches on one of many issues, including double ACK packets and ineffective congestion algorithms.
Therefore, it is advisable to avoid using QUIC on TCP-based proxies. However, if the TCP proxy itself has a good line with few packet losses, and the QUIC traffic is not significant, you might not feel a significant problem in practice. But it still generates unnecessary additional overhead, and performance is far inferior to direct use of TCP layer proxy. Therefore, unless it is for QUIC testing or other developer purposes, please do not adjust the block-quic parameter to allow QUIC traffic.