Clash GeoIP and GeoSite Data Updates: Rule References, Refresh Intervals, and Troubleshooting

Start by separating GeoIP, GeoSite, and rule sets

The short version: GeoIP classifies traffic by destination IP address, while GeoSite classifies it by domain name. They are not interchangeable. When a configuration contains GEOIP or GEOSITE, it only means the rule engine will query the corresponding database; whether traffic is sent direct, through a proxy, or rejected is still determined by the policy at the end of the rule. The database itself does not establish proxy connections or change the current proxy mode automatically.

GeoIP data maps IP ranges to countries, regions, or other identifiable categories. The common rule GEOIP,CN,DIRECT means that when the destination IP is classified as CN by the database, the connection is handed to the DIRECT policy. Different cores may use MMDB, dedicated GeoIP files, or converted internal formats. File names and loading methods vary, so an extension alone cannot prove that the current core is using the database.

GeoSite data stores domain collections and category labels, such as regional domains, common services, or advertising domains. The rule GEOSITE,cn,DIRECT matches the connection's domain against those collections. It is useful for routing by domain before DNS resolution and avoids some of the mistakes caused by CDNs, global traffic steering, and shared IP addresses when relying only on IP geolocation.

A rule set usually refers to an external rule file supplied through rule-providers. It can contain domain names, IP-CIDR entries, or classic rule entries, which are then referenced with RULE-SET. Rule sets and GeoSite can both store domain categories, but their download URLs, refresh intervals, behavior types, and configuration entry points differ. Updating a rule set does not update GeoSite data, and vice versa.

How the configuration references GeoIP and GeoSite

Rules are checked from top to bottom, and matching stops after the first hit. Even if the database updates successfully, traffic will never reach a new rule if that rule is placed after a broader match. When investigating “the database updated but routing did not change,” checking rule order is usually more useful than downloading the files again.

The following is a Mihomo configuration approach for cores that support GEOSITE. Policy-group names must match those in your local configuration; Node Selection in the example is a policy name, not a reserved keyword.

rules:
  - GEOSITE,category-ads-all,REJECT
  - GEOSITE,cn,DIRECT
  - GEOIP,CN,DIRECT,no-resolve
  - MATCH,Node Selection

The first rule handles advertising domains, the second handles CN domains, and the third applies CN address matching once the destination IP is available. The final rule takes over connections that matched nothing earlier. If MATCH is placed first, the database rules that follow will never get a chance to match. Likewise, placing a broader domain rule before GEOSITE,cn,DIRECT may intercept domains that should have gone direct.

no-resolve is commonly used with IP-based rules to prevent the rule engine from triggering an additional domain lookup just to evaluate that match. It does not skip an existing destination IP and does not disable the DNS module. GeoIP can still match connections made directly to an IP; when a connection only has a domain and no real destination IP yet, the rule may not match and traffic will continue to later rules.

Should domain and IP rules both be kept?

Most region-based routing configurations keep both. GeoSite makes the decision while the domain is still available, while GeoIP covers direct IP access, connections without domain information, or traffic not covered by domain rules. Because CDN nodes may be located in different regions, a service's domain and its destination IP do not always point to the same location. For stable service-level routing, put explicit domain or GeoSite categories first, then let GeoIP handle the remaining connections.

Where TUN and Fake-IP mode fit

TUN mode captures more system traffic, but it does not automatically make rule databases more accurate. With Fake-IP DNS enabled, the client returns an internal mapping address to the application; the core attempts to recover the original domain and apply domain rules. When the real connection is established, a destination IP may still be available. If an application connects directly to a hard-coded IP, uses its own resolver, or provides no recoverable domain information, GeoSite may not be involved. In those cases, IP rules and the final fallback policy matter more.

If routing behaves differently after enabling TUN, do not assume the database is damaged. First compare whether the connection retains its domain under the regular system proxy and TUN. Then check the DNS mode, sniffing settings, Fake-IP filters, and rule order. The database only supplies match data; the core's interception method determines the connection context.

Choose an update method with a fallback

Update methods generally fall into three categories: client-managed updates, core-managed automatic updates, and manual replacement. Prefer an update entry already provided by the client or core, since it usually knows the data directory, file names, and reload process. Manual downloads are useful when you need a pinned version, internal distribution, or a way to isolate update failures, but verify format compatibility with the current core before replacing anything.

Client-managed updates

Some desktop and mobile clients provide buttons for updating GeoIP, GeoSite, or rule data in their settings. After you click one, the client downloads the data into its runtime directory. Some implementations restart the core automatically; others apply the change only when the configuration is loaded again. Afterward, check the update result, file timestamp, and core logs rather than relying on the button status alone.

Automatic updates in the Mihomo core

Mihomo versions that support automatic Geo data updates can use the configuration to control whether updates run and how often. Fields, data formats, and default URLs may change between versions, so follow the documentation for the current core and the configuration generated by your client. A common structure looks like this:

geo-auto-update: true
geo-update-interval: 24

geo-update-interval is generally measured in hours. Twenty-four hours is suitable for typical use; there is no need to reduce the interval to a few minutes. Geo data is not a real-time routing table, and overly frequent requests only increase the chances of startup failures, network timeouts, and file-write conflicts. For devices where stability matters, update weekly or during a scheduled client maintenance window, then confirm the result in the logs.

If the configuration also defines geox-url, the core retrieves GeoIP, GeoSite, or MMDB data from the corresponding URLs. The source must provide content the current core can recognize. A web page URL, an archive download page, or a file in another format may return successfully yet fail during loading. When a subscription converter generates the configuration, also make sure remote updates do not overwrite locally configured automatic-update fields.

Manually replacing the database

1. Stop the core in the client first so the database is not overwritten while it is being read.
2. Locate the data directory actually used by the client, not the installation directory or your browser's download directory.
3. Back up the currently working file and record the core version and the original file's modification time.
4. Place the new file in the required format, preserving the file name and access permissions expected by the client.
5. Restart the core and load the configuration, then check the logs for parsing, open, or permission errors.
6. Test rule matching with a specific domain and IP. Do not treat “the file got larger” as proof that the update succeeded.

Check each layer when updates fail or rules do not take effect

Separate “download failed,” “file loading failed,” “the rule is not referenced,” and “the rule matched but the policy result was unexpected.” They may all appear in the interface as a site taking the wrong route, but the fixes are completely different. Check the five layers in order: data download, core loading, configuration parsing, rule matching, and policy execution.

Layer 1: Was the data downloaded successfully?

• Review request status, timeouts, DNS resolution, and connection errors in the logs.
• Confirm that the update traffic itself can reach the data source. During startup, before a proxy has been established, downloads may only be able to use a direct network connection.
• Check the system clock. A significantly incorrect time can prevent TLS connections from being established.
• Check available storage and directory write permissions. On mobile devices, also check whether the system reclaimed app data or restricted background networking.
• Check whether the client wrote the download to the data directory of a different configuration instance.

Layer 2: Did the core load the file successfully?

A completed download does not guarantee that the file can be loaded. If the logs report an invalid database format, a missing tag, a file-open failure, or a parsing error, first restore the last known-good data file. Common causes include an error page saved as the file contents, an incompatible data format, an incomplete file left by an interrupted download, or a file name or directory that does not match the client's expectations.

If errors began only after changing the core, check whether the client is still using data options from the previous core. For example, a client may let you switch between MMDB and other Geo data-loading methods. Changing the core without adjusting the mode can leave the file present but unused.

Layer 3: Does the current configuration actually reference the database?

Search the active configuration for GEOIP, GEOSITE, or the relevant RULE-SET. The original YAML shown on a subscription page may not be the configuration ultimately loaded by the core; the client may merge or override rules through scripts or local patches. Prioritize the client's exported runtime configuration and verify the rule names, policy-group names, and indentation.

GeoSite category names must exist in the current data. After a data source update, categories may be added, split, or renamed. If the configuration references a label that is not present, the core may fail during loading or the rule may not behave as expected. Match category names to the data-source documentation instead of guessing from display text.

Layer 4: Did the rule have a chance to match?

Open the connection log or the client's connection details and inspect the target host, rule type, rule payload, and final policy. If the connection matches MATCH, the preceding Geo rules usually did not match or were never executed. If it matches another DOMAIN-SUFFIX, IP-CIDR, or RULE-SET, adjust the rule order instead of replacing the database again.

When testing GeoIP, also verify the destination address. A domain may return multiple IPv4 or IPv6 addresses that vary by region, network, and time. Existing browser connections, DNS caches, and QUIC sessions may keep using an old address. After changing the configuration, restart the relevant application or clear its connections before testing again.

Layer 5: Is the selected policy usable?

A rule match only determines which policy receives the connection. The connection can still fail if the policy group has selected an unavailable node, latency testing is incomplete, or the direct network cannot reach the destination. The logs may clearly show that the rule matched correctly. Continue by checking the selected policy-group option, node status, DNS results, and the scope of system-proxy interception rather than blaming the Geo data.

Verify the update through rule-match records

Reliable verification should cover configuration loading, a representative domain, a destination IP, and fallback traffic. First confirm that the core startup log contains no Geo data errors. Then choose a domain clearly belonging to the target category and check whether it matches GEOSITE. Next, test a known IP and confirm the GEOIP classification. Finally, test traffic outside those categories and make sure it lands on the expected MATCH or another fallback rule.

If the client supports rule testing or connection details, record four fields: “target, matched rule, policy group, and actual egress.” Seeing a page open is not enough to prove that routing is correct, because both direct and proxied connections may succeed. Conversely, a page failing to open does not necessarily indicate a rule error; the policy node, DNS, IPv6, and application cache can all affect the result.

Suggested update intervals

• Typical personal devices: Check once a week or month, and refresh manually when you notice a clear geolocation change.
• Devices that switch configurations often: Let the client manage updates, and review data-loading logs after every core upgrade.
• Long-running router devices: Set a stable automatic-update window, keep the previous working file, and avoid updating at the same time as a device restart.
• Fixed-rule environments: Pin a verified data version and update it during scheduled maintenance to reduce routing fluctuations caused by category changes.

Minimum checklist after an update

1. The current core supports the Geo rule types used in the configuration.
2. The data files are in the directory read by the active runtime instance.
3. Startup logs show no download, parsing, permission, or category-name errors.
4. The runtime configuration contains the expected GEOIP and GEOSITE rules.
5. No overly broad rule appears early in the order and takes over all traffic prematurely.
6. Connection details show the expected rule and policy were matched.
7. After making changes, establish a new connection so old DNS and session caches do not affect the test.

Maintaining GeoIP and GeoSite is not about chasing the highest refresh frequency. It is about keeping the data format, core capabilities, configuration references, and rule order aligned. After an update, verify the chain step by step—file downloaded, core loaded it, rules referenced it, connection matched, and policy executed—to locate most problems at a specific layer.