12. Observability and Troubleshooting#

Link1 troubleshooting principle: first confirm whether traffic enters Link1, then confirm whether the domain/IP is correct, then confirm rule matching, then confirm policy group selection, and finally confirm whether the outbound protocol succeeds.

Overall Troubleshooting Flow#

1. Whether the core is running
2. Whether traffic enters Link1
3. Whether Link1 knows the correct target
4. Whether rules hit the expected action
5. Whether the policy group selects the expected node
6. Whether the outbound protocol can connect
7. Whether DNS, TUN, HTTP Engine, or other advanced features affect the result

Do not start by changing protocol parameters. Many cases of "node unavailable" are actually caused by the client not entering the proxy, DNS not entering Link1, incorrect rule order, or the policy group currently selecting DIRECT.

Most Common Observation Points in the App#

Location	Purpose
Home status	Confirm whether the core is running, whether the configuration is applied, and whether the real-time rate changes
Connection list	View real connections, targets, matched rules, outbound, and errors
Policy group page	View current selection, node latency, and health status
Provider page	View subscription refresh, filtering results, and node count
DNS/Fake-IP information	Determine whether domains are resolved by Link1
Rule test	Construct a virtual connection to verify rule order and action
Logs page	Locate configuration, DNS, dialing, protocol handshake, and HTTP Engine errors
HTTP capture	View captured HTTP requests/responses

1. Whether the Core Is Running#

First confirm in the app:

The current configuration profile has been applied.

The status shows running.

There are no startup errors such as port conflicts, insufficient permissions, or TUN creation failure.

When running the core directly, you can use:

spark -f config.yaml -t
spark -d . -f config.yaml

If -t passes but startup fails, it is usually an runtime environment issue, such as a port being occupied, no permission to create TUN, missing kernel capabilities on the router, or an incorrect certificate file path.

2. Whether Traffic Enters Link1#

Explicit Proxy#

Verify with a minimal request:

curl -x http://127.0.0.1:7890 https://www.example.com/

Then check whether www.example.com appears in the app connection list.

If it does not appear:

The client proxy address may be incorrect.

The system proxy may not be taking effect.

The browser may be using its own proxy settings.

The request may be skipped by --noproxy or system bypass rules.

You may not be viewing the currently running configuration profile.

TUN#

Check the app or system network settings:

Whether TUN is enabled.

Whether the system default route points to TUN.

Whether auto-route is taking effect.

Whether route-exclude-address excludes the target.

Whether DNS hijack is taking effect.

Router Transparent Proxy#

First verify outbound connectivity on the router itself, then verify from a LAN device. Focus on:

Whether the LAN device's default gateway is the router.

Whether firewall rules import TCP/UDP into Link1.

Whether DNS queries also enter the router.

Whether private networks, side routers, or IPv6 routes bypass it.

3. Whether Link1 Knows the Correct Target#

In connection details, check:

Whether the target is a domain or an IP.

If it is Fake-IP, whether it can be reverse-mapped back to the domain.

Whether Sniffer identifies HTTP Host / TLS SNI / QUIC SNI.

Whether DNS logs contain the domain.

If the rule is DOMAIN-SUFFIX,example.com,PROXY, but the connection details only show 93.184.216.34:443, the domain rule may not match. Fixes:

Explicit proxy scenario: let the client pass the domain to the HTTP/SOCKS proxy.

TUN/transparent proxy scenario: enable Link1 DNS, Fake-IP, and DNS hijack.

HTTPS/QUIC scenario: enable Sniffer as needed, but do not treat Sniffer as a DNS replacement.

4. Whether Rules Match as Expected#

Use the app's rule test to enter the target host, IP, port, network type, inbound type, and source IP, then confirm:

Whether it matches the rule you expect.

Whether it matches an earlier rule too soon.

Whether it falls through to the final MATCH.

Whether the action is a node, policy group, DIRECT, or REJECT.

When real connections and rule tests differ, first compare metadata: does the real connection only have an IP? Is the inbound type different? Is the source IP different? Is the port different?

5. Whether the Policy Group Selects the Expected Node#

On the policy group page, confirm:

Which group the rule action points to.

Which member is currently selected in that group.

Whether the member is healthy.

Whether an automatic group selected another node due to latency testing.

Whether the provider introduced by use actually has nodes.

Common misunderstandings:

Symptom	Explanation
Rule points to `PROXY` but actually uses `DIRECT`	`DIRECT` is currently selected in the `PROXY` group
`url-test` does not select the node you want	It selects based on the test URL result, not based on the target website
Subscription refresh succeeds but the group is empty	`filter`/`exclude-filter` filtered out the nodes
Node is shown as available but a specific website is slow	The health check URL differs from the target website path and can only represent partial network quality

6. Whether the Outbound Protocol Is Reachable#

Outbound failures usually fall into four categories:

Category	Typical Symptoms	Checkpoints
DNS/network unreachable	timeout, no route, connection refused	Whether `server` can be resolved and the port is reachable
Authentication failure	auth failed, bad password, invalid user	Whether the password, UUID, token, and username are correct
TLS/fingerprint failure	certificate, handshake, fingerprint errors	`sni`, `servername`, `skip-cert-verify`, `client-fingerprint`
Protocol parameter mismatch	QUIC/TUIC/Hysteria2 handshake failure	Version, ALPN, congestion control, upload/download bandwidth, UDP switch

Troubleshooting order:

Use a minimal configuration with only one node and MATCH.

Select that node directly in the policy group.

Start a simple request.

Check the first protocol-related error in the logs.

Compare against Outbound Protocol Configuration and check required fields.

7. Common DNS Issues#

Symptom	Common Cause	Fix
Domain rules do not match	DNS does not enter Link1	Enable `dns.enable`, TUN `dns-hijack`, or explicit proxy domain forwarding
Domestic websites use the proxy	Incorrect rule order or GeoData unavailable	Check `RULE-SET`, `GEOIP`, and Geo files
Some domains resolve slowly	nameserver timeout or too much fallback	Shorten the upstream path and split DNS by domain
Fake-IP cannot access intranet	Intranet domains are assigned Fake-IP	Add to `fake-ip-filter` or hosts
IPv6 results are abnormal	Global `ipv6` and `dns.ipv6` are inconsistent	Explicitly decide whether to enable IPv6

8. Common TUN Issues#

Symptom	Common Cause	Fix
Network disconnects after enabling	Default route conflict, DNS not taken over, or outbound also captured by TUN	Check `auto-route`, `strict-route`, and excluded addresses
Only the browser works	The browser still uses an explicit proxy, while system traffic does not enter TUN	Confirm TUN status and system routes
UDP does not work	The outbound node does not support UDP or the transparent proxy path does not support it	Check node `udp` and protocol capabilities
LAN access is abnormal	Private addresses are proxied or affected by Fake-IP	Add private network rules, route exclude, and fake-ip-filter
macOS platform conflict	Multiple transparent entry points are enabled at the same time	Keep only one takeover method

9. Common Provider Issues#

Symptom	Common Cause	Fix
provider has no nodes	Download failed, format is incorrect, or filtering is too strict	Check errors and node count on the Provider page
Subscription has nodes but the group does not	`proxy-groups.use` does not reference the provider	Check group configuration
Selection is lost due to node name changes	Node names changed after subscription update	Use a stable provider or manual group
All health checks fail	Test URL is unreachable or all nodes are unavailable	Change the test URL and confirm basic network connectivity
WARP candidates are unavailable	Account/key/endpoint/local UDP issue	Check each item against the WARP provider example

10. Common HTTP Engine Issues#

Symptom	Common Cause	Fix
No capture	Capture is not enabled, host does not match, or traffic does not enter HTTP Engine	Check `http-engine.enabled`, `capture.enabled`, and match
Cannot see HTTPS body	MITM is not enabled or the client does not trust the CA	Configure `mitm.hosts` and install the CA
Websites cannot open after enabling	Certificate is not trusted, rule is fail-closed, or body is too large	Narrow the MITM host scope and change to `on-error: fail-open`
Rewrite does not take effect	match conditions do not match or direction is wrong	Check the flow's host/path/method and rule direction
Capture uses too much disk	Full body is saved and limits are too large	Reduce `max-flows` and `full-body-max-bytes`

11. Log Keyword Quick Reference#

Keyword	Layer	Explanation
`compile config`	Config compilation	YAML field, reference, or composition errors
`listen` / `bind`	Inbound	Port in use or permission issues
`tun` / `route`	TUN	Virtual NIC, routing, or permission issues
`dns`, `resolve`, `rcode`, `nameserver`	DNS	DNS upstream, Fake-IP, or routing issues
`rule` / `match`	Routing	Rule hits or rule-set loading issues
`provider`	Provider	Subscription download, file reading, filtering, or health checks
`dial` / `connect`	Outbound	Remote connection failure
`handshake`	Protocol/TLS	Authentication, certificate, fingerprint, or protocol parameter errors
`mitm` / `capture` / `rewrite`	HTTP Engine	Certificate, capture, or rewrite rule issues

Plain-English Translations of Common Network Errors#

Error text may vary slightly across platforms, but the meaning is generally the same. During troubleshooting, do not look only at the last error. Consider whether it occurs during DNS, dialing, TLS handshake, or the HTTP Engine stage.

Error/Keyword	Plain meaning	Common causes	Check first
`connection refused`	The peer received the connection, but nothing is listening on the port	Wrong port, service not started, firewall actively rejecting	`server`/`port`, upstream service status
`timeout` / `i/o timeout`	Timed out while connecting, reading, or writing	Network unreachable, UDP blocked, upstream too slow, DNS stuck	DNS resolution result, port reachability, node health
`no route to host`	The local machine does not know how to reach the target	Incorrect routing table, TUN/transparent proxy route conflict, gateway unreachable	TUN `auto-route`, excluded routes, default gateway
`network is unreachable`	The target network is unreachable	IPv6 enabled but the local machine has no IPv6, missing route	`ipv6`/`dns.ipv6`, `ip-version`
`EOF`	The peer closed the connection early	Protocol mismatch, TLS/SNI error, upstream actively closed	Protocol `type`, TLS, SNI, authentication fields
`unexpected EOF`	The connection closed in the middle of reading	Intermediate link dropped, server closed, certificate/protocol failure	First handshake error, upstream logs
`tls: certificate`	Certificate verification failed	SNI mismatch, self-signed certificate, incorrect system time	`servername`/`sni`, `skip-cert-verify`, time
`handshake failure`	Protocol handshake failed	Password/UUID/ALPN/REALITY/obfs mismatch	Required fields and combination tables in the protocol chapter
`authentication failed` / `auth failed`	Authentication failed	Incorrect username, password, UUID, or token	Whether credentials were copied completely and whether there are extra spaces
`context canceled`	The request was canceled	User closed the connection, timeout protection triggered, config switched	Whether it was stopped manually, whether there was a timeout/reload
`body exceeds max size`	The body exceeds the size allowed for rule reading	HTTP Engine/JQ/QuickJS body is too large	`max-size`, `body-max-size`, whether the body really needs to be read
`body is required but unavailable`	The rule requires a body, but no readable body is available	Streaming body, no body, wrong direction	`require-body`, `direction`, match conditions
`ReferenceError`	QuickJS accessed a variable/object that does not exist	Typo, or use of unavailable environments such as `console`/`fetch`/DOM	QuickJS debugging methods

12. Common Issue Handling#

The browser is configured with a proxy but has no traffic#

Confirm that the browser proxy port is mixed-port.

Use curl -x for a minimal verification.

Check whether requests appear in the App connection list.

If not, check system proxy bypass rules and browser proxy extensions.

A domain rule is configured but does not match#

Check whether the target in connection details is a domain or an IP.

If it is an IP, check whether DNS enters Link1.

Enable Fake-IP and DNS hijack under TUN/transparent proxy.

Enable Sniffer as a supplement if necessary.

A policy group has a selected node but still connects directly#

Check the action matched by the actual connection rule.

Confirm whether the action really points to this policy group.

Check whether an earlier DIRECT rule matched first.

Check whether SUB-RULE, AND, or OR changes the flow.

No websites can be opened through a specific node#

Use a minimal configuration that keeps only this node.

Confirm that the server address and port are reachable.

Check required protocol fields.

Check TLS/SNI/fingerprint and certificate verification settings.

If it depends on dialer-proxy, verify that the fronting node works first.

LAN devices cannot use Link1 on a router#

Confirm that the LAN devices' gateway and DNS point to the router.

Confirm that Link1 is listening on an address reachable from the router.

Confirm that firewall/routing rules direct traffic into Link1.

Check whether private addresses are incorrectly proxied.

Test TCP, UDP, and DNS separately.

13. What to Provide When Reporting an Issue#

Recommended information:

Link1 App version and core version.

Current platform: Windows/macOS/Linux/router/mobile phone.

Entry mode: explicit proxy, TUN, router transparent proxy, or listener.

Minimal reproducible configuration, with sensitive information such as passwords, private keys, and subscription URLs removed.

App connection details screenshot or copied text.

Relevant log snippets, starting from the first error. Do not capture only the last line.

The rule you expected to match and the rule that actually matched.

The outbound you expected to use and the outbound actually used.

Do not publicly disclose subscription URLs, node passwords, WireGuard private keys, enterprise VPN credentials, HTTP Capture bodies, or full certificate private keys.