1. YAML Structure and Configuration Sources

Keep three things separate: a subscription link is a URL for fetching config, a Profile is a config entry managed by the client, and the effective config is what the core actually loads. Remote Profiles may also be processed by client settings, overrides or scripts. A field in the original subscription doesn’t necessarily have the same value in the running config. When troubleshooting, check the client’s runtime config preview first, then trace where each field came from. This is more useful than repeatedly editing the subscription file.

How Top-Level Sections Reference Each Other

Here’s a direct-connection baseline for checking the config loading process. It includes a mixed port, a mode, an empty proxy list, a manual policy group and a catch-all rule. All requests go direct, so it does not provide remote proxy access. Confirm that this baseline loads before adding provider-supplied proxies one at a time. That helps distinguish structural errors from remote connection issues instead of introducing several variables at once.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
ipv6: false

proxies: []

proxy-groups:
  - name: "Outbound"
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,Outbound

proxies defines remote connections, proxy-groups organizes proxies or other groups into selectable targets, and rules routes requests to those targets. Rules refer to names, not the order of entries in the file. Names must match exactly; spaces, capitalization and full-width punctuation can all cause mismatches. For readability, define proxies first, groups next and rules last. YAML does not require top-level keys to appear in that order.

Indentation, Lists and Strings

YAML uses indentation to show hierarchy. Use two spaces consistently, never tabs, and align fields at the same level. List items start with a hyphen and a space; their properties are indented one level further. A space usually follows the colon in a key-value pair. Quote proxy names, passwords and text containing colons or hash marks. Numeric-only passwords especially should be quoted so the parser treats them as strings, not numbers.

A hash mark outside quotes usually starts a comment. Pasting a password with special characters into an unquoted field may turn everything after the hash into a comment. The file can still parse, but authentication will fail. Use true and false for booleans, integers for ports and [] for an empty list. Don’t paste a full-width colon copied from an interface into your config: it looks similar, but it won’t separate a YAML key from its value.

TypeExampleWhat to Check
Mappingmode: ruleKey name and space after the colon
List- MATCH,DIRECTSpace after the hyphen
Stringname: "Outbound"Matching quotes and consistent names
Booleanallow-lan: falseDon’t quote the value

One File vs. Multiple Profiles

Multiple Profiles are usually alternatives, not layers that automatically combine. The selected Profile is the client’s primary source; whether global overrides still apply depends on the client’s scope settings. Pasting two complete subscriptions together can duplicate top-level keys or overwrite proxies with the same name. To combine sources, use a proxy provider or the client’s merge feature explicitly rather than relying on how duplicate keys happen to be parsed.

When a remote config updates, the newly downloaded content may replace edits made directly to the original. Keep personal rules in a separate override; for temporary experiments, make a local copy of the Profile and give it a distinctive name. For details on importing, deleting and switching Profiles, see Managing Profiles and Multiple Configs. The sections below assume the effective config has one clearly defined structure.

2. Ports, Mode and Runtime Settings

General settings determine where the client accepts requests, which proxy mode it uses and how much it logs. Before changing anything, identify how requests enter the core: through the system proxy in a browser, a proxy specified separately for a command-line app, or TUN routing for the whole device. These entry points can coexist, but they are not the same switch. A listening port only means the core is ready to accept connections; if an app doesn’t send requests to it, no proxy connection will be made.

port, socks-port and mixed-port

port provides an HTTP proxy endpoint, socks-port provides a SOCKS endpoint, and mixed-port accepts both types of connection on the same port. For everyday desktop use, a mixed port is usually enough; there’s no need to enable every endpoint just to make the config look complete. Port numbers aren’t fixed. You can change them, but you’ll also need to update the client’s system proxy settings, browser extensions and command-line environment variables.

mixed-port: 7890
allow-lan: false
bind-address: "127.0.0.1"
mode: rule
log-level: info
ipv6: false

profile:
  store-selected: true

This example accepts requests from the local device only. To connect other devices on the same LAN, you also need to consider allow-lan, the bind address and the system firewall—not just turn the setting on. Listening on all network interfaces expands access and should never expose the proxy directly to an untrusted network. When you’re done sharing, restore local-only listening and check your router for port forwarding; remove any forwarding rules you no longer need.

FieldPurposeHow to Check
mixed-portHTTP and SOCKS on one endpointCheck which proxy port the app uses
allow-lanAllow LAN devices to connect to the proxyCheck the bind address and firewall
modeChoose rule, global or direct modeCheck the current mode in the runtime interface
log-levelSet the level of log detailUse debug temporarily for troubleshooting, then switch back

Mode controls routing; it doesn’t enable the system proxy

rule routes requests according to rules, global sends ordinary requests through the global policy, and direct connects ordinary requests directly. Global mode does not automatically take over every app on the device: traffic that never enters the core is still outside its control. Use rule mode for everyday browsing. To troubleshoot a particular site, briefly switch to global mode and compare results to see whether routing is the issue. Then switch back to rule mode so requests that should go direct aren’t sent through a remote proxy.

profile.store-selected saves policy group selections so they can be restored after a restart, but it does not save YAML edits. Renamed groups, removed proxies or a cleared cache can all change what gets restored. If options look different after switching subscriptions, check the group’s current members instead of relying on what you remember selecting last time. For when to use each mode, see Rule, Global and Direct Modes Explained.

TUN Is a Separate Traffic Entry Point

TUN uses a virtual network interface and routing to capture traffic from apps that don’t follow the system proxy. Here’s a common configuration, but before enabling it, make sure the client has installed the required service and has system permissions. Desktop clients may manage these fields through their interface; editing the source file may not change the runtime state if TUN is disabled in the UI. Mobile clients generally use the system VPN interface, so desktop service installation steps don’t apply.

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

stack selects the network stack implementation; check the current mihomo core for supported values. Changing stacks is not a universal fix for network issues. auto-route sets up routes, while auto-detect-interface attempts to identify the outbound interface. Multiple network adapters, other VPNs and virtual machine networks can affect detection. DNS hijacking mainly handles matching standard DNS requests; it doesn’t mean encrypted DNS inside every app is captured.

3. DNS, fake-ip and Resolution Paths

DNS resolves domain names to IP addresses, but in a proxy config it also affects rule matching, proxy server resolution and connection paths. Separate two types of domain: the destination domain for a website, and the proxy server’s domain when establishing the proxy connection. The latter can create a loop if it depends on a proxy that isn’t connected yet. If all proxies fail at once, first check whether their server domains resolve instead of immediately changing website rules.

Start with a Simple, Understandable DNS Config

This example uses fake-ip and specifies upstream resolvers as well as a resolver for proxy server domains. It doesn’t set a listening port, avoiding a direct conflict with a local DNS service. Check the client’s TUN or DNS integration settings to see how system requests reach the core’s DNS. Whether the public resolvers in this example are reachable depends on your network. Test reachability locally before using them; resolver addresses aren’t a one-size-fits-all answer for every region.

dns:
  enable: true
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "*.local"
  default-nameserver:
    - 223.5.5.5
  proxy-server-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query

default-nameserver resolves the domain names of DNS upstreams themselves; this is often called bootstrap resolution. It is not simply a backup resolver for website queries. nameserver specifies the upstream used for regular queries. proxy-server-nameserver resolves proxy server domains, making the resolution path for proxy connections easier to control. If the proxy uses a domain name and the upstream is reachable only through that proxy, check for a dependency loop at this layer.

fake-ip Returns a Virtual Address, Not a Proxy Address

In fake-ip mode, the core can return a virtual address to the app, keep a domain-to-address mapping and handle the subsequent connection. An address in the 198.18 range doesn’t mean the website is actually on that network, and it doesn’t by itself indicate DNS poisoning. What matters is whether the connection still passes through the same core and whether the mapping is valid. If an app bypasses the core and connects directly to that virtual address, the connection will fail. When enabling fake-ip, make sure traffic capture is complete.

fake-ip-filter excludes domains that need real IP addresses from virtual-address responses. LAN device discovery, some games and specialized authentication apps may need individual entries, but don’t exclude every domain at the first sign of trouble. Find the specific domain in the logs, add the narrowest filter entry you can, then clear the relevant cache and try again. *.lan and *.local are examples only; check which domains your LAN actually uses.

FieldWhat It HandlesCommon Misconception
default-nameserverResolve DNS upstream hostnamesNot the only route for regular queries
nameserverHandle regular domain queriesEncrypted transport doesn’t mean the query uses a proxy
proxy-server-nameserverResolve proxy server hostnamesAvoid relying on a proxy that isn’t connected yet
nameserver-policyChoose an upstream for specific domainsSelects a resolver, not the traffic exit

Domain policy, routing policy and caching are handled separately

If only internal domains need to use an internal DNS server, use nameserver-policy to specify a resolver for them. But which DNS server resolves a domain and which proxy handles the website connection are separate decisions; rules control the latter. An HTTPS URL for encrypted DNS only describes the transport—it doesn’t guarantee that queries use a proxy. Before enabling options that make DNS follow rules, plan how proxy domains and upstream hostnames will resolve to avoid a dependency loop.

Check IPv6 one link at a time. The top-level ipv6 setting, whether DNS returns AAAA records, whether the proxy supports the destination address and whether the system has a usable route are related but distinct. After changing resolution modes, the OS, browser and apps may still use cached data. Close relevant connections and clear caches as needed, then test the same domain again. A browser page still working on an existing connection doesn’t prove the new resolution path is correct.

4. Proxy Fields and Proxy Providers

A proxy definition describes the settings for one remote connection; it doesn’t decide which websites use it. Common fields include the name, protocol, server address and port, plus any authentication and transport settings required by the protocol. Provider-supplied URIs, QR codes and subscriptions may include additional parameters. When recreating a proxy manually, don’t copy just the address and password. Identify the protocol first, then check the fields required by that protocol instead of mixing parameters from different guides.

Check Common Fields First, Then Protocol-Specific Fields

Here’s a Shadowsocks example. The hostname and password are for illustration only and won’t connect; replace them with values from your provider. name is a local reference and can be changed to something recognizable. server must be a resolvable hostname or valid IP address, not a webpage URL. port is the remote service port, not the local mixed proxy port.

proxies:
  - name: "Example SS"
    type: ss
    server: proxy.example.com
    port: 8388
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

cipher must match the server configuration; don’t change it just to use something that looks newer. Password format requirements can also vary by encryption method. udp: true allows the proxy to handle relevant UDP traffic, but the protocol, server and network path must all support it. If web browsing works but games or voice calls fail, repeatedly enabling this field won’t solve the problem. Check whether that traffic enters the core and whether the remote server allows it.

FieldWhere to Get ItWhat Goes Wrong
nameSet locally; keep it uniqueGroups can’t find it, or it’s hard to tell apart
typeProvider’s protocol documentationUnsupported fields or handshake failures
server / portRemote connection parametersResolution errors, connection refused or timeouts
Authentication fieldsProtocol parameters such as password and user IDAuthentication fails; a local port is not a substitute

TLS, SNI and Transport Settings Are Not Interchangeable

For protocols that use TLS, the server address and TLS verification name may differ. In Trojan, for example, sni is used during TLS name negotiation and should generally match the server certificate and configuration requirements. It is not an arbitrary domain for speeding up the connection, and it may differ from the IP used to connect. WebSocket paths, HTTP Host headers and other transport parameters are separate layers that must also match. Setting SNI won’t configure them automatically.

proxies:
  - name: "Example Trojan"
    type: trojan
    server: proxy.example.com
    port: 443
    password: "your-password"
    sni: proxy.example.com
    skip-cert-verify: false
    udp: true

For certificate errors, first check the system clock, SNI, server certificate and connection target. Don’t disable verification as a permanent fix; doing so bypasses important identity checks and can hide incorrect settings. If your provider requires a special certificate or public key parameter, configure it according to the protocol documentation. Don’t copy fields from another protocol into this proxy. Older clients may import YAML without supporting every feature in a newer core. If needed, choose a suitable client on the client downloads page.

proxy-providers Manage Proxies; rule-providers Manage Rules

Proxy providers keep proxy sources separate; policy groups reference them by name through use. This example uses a local file to make the structure easier to understand. Relative paths are based on the config working directory, not necessarily the Downloads folder. The file should contain a proxies list, not a complete config with ports and rules. An HTTP provider also needs a valid download URL, update interval and writable cache path, and the provider’s link must be compatible with the expected format.

proxy-providers:
  Local proxies:
    type: file
    path: ./providers/local.yaml

proxy-groups:
  - name: "Subscription Proxies"
    type: select
    use:
      - Local Proxies

Protect remote source URLs because they may contain account credentials. Before sharing a config, remove full subscription URLs and passwords—not just proxy names. If a provider fails to load, check the path and format first, then network access, and finally whether the group references it correctly. A policy group with no available members can’t provide the expected route. Confirm separately that the provider imported, proxies are present and a connection can actually be established.

5. Policy Group Types and References

Policy groups sit between rules and proxies, making them a good place to keep stable names in your config. Rules can always point to “Proxy” while the group’s members change as subscriptions update. That way, you don’t have to edit rules every time a proxy changes. A group doesn’t create a new protocol or make a proxy that lacks UDP support handle UDP. It only determines which candidates are available and when the selection can change.

select Is for Manual Picks; Automatic Groups Choose Candidates

select is a manual group, useful for presenting automatic groups, direct connections and a few fixed proxies side by side. url-test regularly tests candidates and selects based on the results. fallback prioritizes available candidates in the configured order. A test result only reflects a probe to the specified URL; it doesn’t mean every website will be faster or indicate available bandwidth. Choose a group type based on whether you want a fixed preference or automatic adjustments.

proxy-groups:
  - name: "Proxy"
    type: select
    proxies:
      - Auto Select
      - DIRECT

  - name: "Auto Select"
    type: url-test
    use:
      - Local Proxies
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

rules:
  - MATCH,Proxy

This example uses the “Local Proxies” provider from the previous section. If you copy this snippet on its own, add the provider definition first. interval sets the test interval in seconds; tolerance helps prevent frequent switching due to small differences. Use a stable probe URL suited to your network. If the URL is restricted along a particular route, test results may be misleading. The example uses a real URL intended for testing, but confirm that it’s reachable in your environment before deploying it.

TypeHow It ChoosesBest For
selectUser selects a member manuallyMain entry point or fixed traffic route
url-testSelects based on probe resultsEveryday browsing where automatic adjustments are acceptable
fallbackSelects available members in orderPrimary and backup routes with clear priorities
load-balanceDistributes connections according to a policyMulti-exit setups that account for session requirements

Load Balancing Does Not Combine Speeds for One Connection

load-balance can distribute separate connections across candidates, but it generally can’t combine multiple proxies’ bandwidth into one download connection. Some services also expect a consistent exit IP, such as account logins, payments and certain long-lived connections. If you don’t have a specific need, a manual or automatic selection group is usually easier to reason about. Consider load balancing only after understanding its distribution strategy and session requirements.

A successful automatic test doesn’t mean existing connections will immediately move to a new proxy. Established connections usually keep their original route; new connections reflect the group’s current selection. When troubleshooting, check the actual path in the connection log, then send a new request. Don’t assume all traffic has moved just because the group UI highlights a different option. Restarting the core clears connections but interrupts active traffic, so it usually isn’t necessary after every switch.

Use Stable Group Names to Isolate Subscription Changes

Create a stable business group such as “Proxy” or “Work,” and point rules to those names. Inside, connect it to a proxy provider or an automatic group. Keep the hierarchy simple: rules to business groups, business groups to candidate groups, and candidate groups to proxies. Circular references are useless and may prevent the config from loading. For example, if group A contains B and B contains A, change the relationship to one-way.

Name collisions also matter. Avoid giving a proxy and policy group the same name, or it’ll be hard to tell them apart when reading the runtime route. Provider updates may change member names, which can prevent manual selections from being restored. Provider references can reduce the impact of stale static proxy names, but you still need to make sure the provider has valid members. Start with a simple regex filter, inspect its results and then narrow it down; an overly restrictive pattern can filter out every candidate.

On mobile devices, also consider how often probes run. Multiple automatic groups and proxy providers doing health checks can create duplicate requests. Shortening the interval doesn’t necessarily make things more reliable. Remove redundant tests, keep only the candidates you actually use and compare background behavior. If battery drain seems high, see Mobile Background and Battery Troubleshooting. Don’t assume a single battery change means the core is at fault.

6. Rule Order, Syntax and Rule Sets

Rules in rule mode are evaluated from top to bottom. Once a rule matches, its policy is used; the core doesn’t keep searching for a “more specific” rule later in the list. Put exceptions first, broader rules later and finish with MATCH to catch everything else. Similar-looking rule types don’t necessarily match the same scope. Choose the right type to match a domain, its subdomains or a substring.

Understand Domain Rules and IP Rules Separately

DOMAIN matches an exact domain. DOMAIN-SUFFIX matches the domain itself and its subdomains. DOMAIN-KEYWORD matches a substring and has broader scope, making false positives more likely. For a specific site, prefer an exact domain or suffix instead of using a keyword just because it’s shorter. Don’t include a protocol prefix or webpage path in a rule domain. A domain rule generally can’t distinguish individual URLs on a site.

rules:
  - DOMAIN,internal.example.com,DIRECT
  - DOMAIN-SUFFIX,example.com,Proxy
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  - MATCH,Proxy

In this example, the internal site goes direct first; other requests to example.com use the proxy group. If you swap the first two rules, the internal site will match the broader suffix rule first. Use IP-CIDR for IP ranges and IP-CIDR6 for IPv6. no-resolve means the core won’t actively resolve a domain just to evaluate the IP rule. It doesn’t mean the request never needs DNS; if the destination already has an IP address, it can still be matched by IP.

Rule TypeWhat It MatchesTip
DOMAINExact domainUseful for a few specific exceptions
DOMAIN-SUFFIXDomain and subdomainsDon’t include URL paths
IP-CIDRIPv4 rangeDistinguish triggering resolution from matching an address
RULE-SETExternal rule setCheck the set name and file format
MATCHAll remaining requestsUsually placed at the end of the rules

The rule set behavior must match its file contents

Rule sets make it easier to maintain long domain lists separately. Use domain for domain lists, ipcidr for IP ranges and classical for classic rule sets that include rule types. A complete Clash config is not a rule set, and a proxy subscription URL doesn’t belong in a rule set source. This example uses a local domain set: the main config specifies the route, while the set file lists only what to match.

# Snippet for the main config
rule-providers:
  Work Domains:
    type: file
    behavior: domain
    format: yaml
    path: ./rules/work.yaml

rules:
  - RULE-SET,Work Domains,Proxy
  - MATCH,DIRECT
# ./rules/work.yaml
payload:
  - "example.com"
  - "+.example.org"

In this example, example.com is an exact domain entry, while +.example.org covers the domain and its subdomains. A classic rule set can contain typed entries such as DOMAIN-SUFFIX,example.org, but don’t add a policy target to the entries themselves. The main config’s RULE-SET specifies the target. HTTP rule sets also need an update interval and cache path. If the initial download fails, check for a usable cached copy; an update failure doesn’t necessarily stop all rules from working.

Check the Actual Match in Connection Logs

After changing rules, send a new request and check the domain, matched rule and policy chain in the connections view. A browser page may also request login, image and API domains, so changing a rule for the main address-bar domain may not be enough. Find the specific failing request, then add the narrowest rule you can. Don’t route every match for a broad keyword through the same proxy. Encrypted DNS inside an app, connection reuse or connections made by IP can also affect which domain is visible.

Process rules can route desktop apps, but the core must be able to identify process information, and results may vary with OS permissions and traffic entry points. Verify them on your own platform before relying on them; process names aren’t universal across platforms. GEOIP and other geographic rules also depend on the relevant data files and their update status. First verify routing with a few clear domain rules, then add larger rule sets. Troubleshooting will be much easier.

7. Overrides, Merges and Subscription Updates

Overrides keep personal settings separate from remote subscriptions; they shouldn’t become another large file that duplicates almost everything. Common needs include setting a fixed local port, adding exceptions for internal sites, creating stable policy groups and changing DNS. Override formats and processing order vary by client. First confirm whether the client replaces fields, recursively merges, prepends rules or runs a script. Don’t treat a client-specific control key as a native mihomo field.

First Decide What to Change and Which Configs It Affects

A typical processing chain is: fetch remote content, apply client conversions or extensions, apply personal overrides, then pass the result to the core. The actual order may also include global settings and runtime changes, so rely on the client’s effective config. For an exception needed by just one subscription, bind it to that Profile. Use global scope only for local settings needed across all configs. Too broad a scope may make another subscription reference a group that doesn’t exist.

Before adding an override, copy the original config and note the current mode, group selection and a test target you can reproduce. Then change one type of field at a time—for example, set DNS first without changing proxies and rules. Once it loads, compare the source file with the effective config: did the value change as expected, are the original lists still present, and is the target group still there? Confirm the result before moving on. This is more reliable than adding every change at once because the UI says “saved.”

Overriding a Scalar Is Not the Same as Merging a List

A scalar such as mode is often overwritten by the later value. A mapping such as dns may be merged recursively or replaced entirely. Lists such as rules are especially prone to being replaced wholesale. Two clients can use the word “merge” and still behave differently. The example below illustrates the before-and-after semantics; it is not override syntax you can paste into every client.

Original Subscription Rules

rules:
  - DOMAIN-SUFFIX,example.org,Proxy
  - MATCH,Proxy

Desired Final Rules

rules:
  - DOMAIN,intranet.example.com,DIRECT
  - DOMAIN-SUFFIX,example.org,Proxy
  - MATCH,Proxy

The goal here is to put an exception first while keeping the existing rules. If the client only supports replacing lists, you must explicitly build the complete result. If it supports prepending rules, use that feature instead. Adding another rules key at the end of the file won’t automatically put a rule first. Don’t rely on YAML anchors to concatenate lists across files, either: anchors are for references within one document and can’t replace the client’s merge process.

What You ChangeBehavior to ConfirmWhat to Check
Ports and modeDoes the UI take control again?Effective values match runtime state
DNS mappingRecursive merge or full replacement?Required resolver fields are still present
Rule listPrepended, appended or replaced?Exceptions come first; catch-all comes last
Policy group listMerged by name or recreated?References resolve and members are intact

Consider groups with matching names and dynamic proxies together

Group names in subscriptions may change, leaving personal rules without a valid target. Create a business group with a stable name and have it reference a proxy provider, or build its members conditionally in a script that the client explicitly supports. Scripts should handle empty proxy lists and name conflicts. Don’t assume every download has the same proxies, and never silently select an unverified route when no candidates are found.

Avoid storing provider credentials again in personal overrides, so a password change in the subscription doesn’t require updating two places. If manual proxies and subscription proxies must coexist, use distinct names and note where each comes from. To troubleshoot a failed merge, disable personal extensions first and confirm that the original subscription loads. If the original subscription is already broken, fix the source before changing the merge. For a closer look at the top-level structure, see A Section-by-Section Guide to config.yaml.

8. Config Validation, Troubleshooting and Recovery

Validation has three layers: the file parses, the core accepts it, and requests behave as expected. Valid YAML only passes the first layer. The core may still reject unsupported fields, missing group names or incorrectly formatted rule sets. A successful startup also doesn’t mean every remote host is reachable. Checking these layers in order helps distinguish startup problems from network problems and avoids unnecessary client reinstalls.

Check the Config Statically, Then Test the Runtime Path

If you have the mihomo command-line core installed, run the test command from the directory containing the config. On Windows, use the corresponding executable name; on other systems, use the actual installation path. The commands below assume the executable and config.yaml are in the current directory. A config test can’t confirm that your provider account is valid, all remote resources are downloadable or every rule routes traffic as intended. Desktop client users can also use the config validation feature in the UI.

# Linux / macOS: run from the test directory
./mihomo -t -d . -f ./config.yaml

# Windows PowerShell: run from the test directory
.\mihomo.exe -t -d . -f .\config.yaml

For relative path issues, start by setting an explicit working directory. -d . uses the current directory as the config working directory; files referenced by rule sets and proxy providers must also be in the expected locations. Don’t move a running client’s data directory just to pass a test. For isolated testing, copy the required files to a separate directory. This makes paths easier to verify and keeps debugging from affecting your main config and cache.

SymptomCheck FirstNext Step
Line number reported or parse failureIndentation, quotes, colons and duplicate keysCheck the reported line and the section above it
Proxy or group not foundNames and provider referencesCheck what’s actually defined in the effective config
Can’t listen on the portPort conflict, bind address and permissionsClose the conflicting app or change the endpoint consistently
Connection timeout or handshake failureDNS, remote address and protocol settingsTest resolution and connection separately
Only some sites failMatched rule, actual route and related domainsCompare direct and proxied paths

Read logs for one reproducible request at a time

For more detail, temporarily set log-level to debug, close unrelated apps and visit one specific destination. First check whether the request reaches the core, then inspect the matched rule and policy chain, and finally look at connection errors. If there’s no request in the logs, the issue may be the system proxy, the app’s proxy settings or TUN capture—not the remote proxy. If the policy chain is correct, check DNS, authentication and TLS.

Don’t assume every error log points to the same problem. A background rule set update can fail while a website continues to work with the existing cache. A single test URL can fail without affecting other traffic. When sharing logs, keep the error context and event order, but remove subscription URLs, credentials and domains you don’t want to disclose. A screenshot of “timeout” alone usually doesn’t show whether the failure occurred during resolution, connection or handshake.

Use Comparisons to Confirm a Fix, Not Guesswork

You can test a proxy endpoint by explicitly sending an HTTP request through it. The command below only checks whether a request can go through the local mixed port. It doesn’t prove that the whole system is routed through the core, and it doesn’t test UDP. Confirm that the core is listening on the specified port first. If the connection is refused, check the local service and port before changing subscriptions. Choose a test destination with a clear expected result on your current network.

curl -I --proxy http://127.0.0.1:7890 https://example.com

Next, visit one destination that should go direct and another that should use a proxy, then check the results in the connections view. After changing rules, create a new connection; after changing DNS, account for cached data; after switching groups, inspect the actual route. Record what you changed, what you tested and what you observed. Keep only changes whose effects you can explain. If you still can’t find the issue, follow the Proxy Timeout Troubleshooting Checklist or look up the symptom in the Help Center.

Recovery and Ongoing Maintenance

To recover, disable new overrides first, then switch back to a verified Profile. If the problem persists, check whether the system proxy or TUN still has an incompatible endpoint configured. Don’t delete every config, cache and log at once—you’ll lose useful comparison data. For client selection, consider Clash Plus first, then compare other options based on your OS and feature needs. Find installers on the client downloads page. If an older client lacks support for a field, check the core’s capabilities instead of repeatedly changing indentation.

Once the config is stable, switch debug logging back to its usual level, remove obsolete test entries and keep a short record of your changes. Back up personal overrides and any required local provider files; saving the subscription URL alone won’t restore all your personal rules. After future updates, spot-check a few consistent scenarios to catch changes to rule order, group members or DNS paths quickly. To go through the connection setup again, return to the quick-start guide. Use this page as your field reference.