Advanced 13 min read

GeoIP and GeoSite Database Update Guide: Fixing Incorrect Rule Matches

GEOIP and GEOSITE rules rely on local geolocation databases. Outdated files can send traffic to the wrong policy. Learn what each database does, where to get them, how to configure mirror URLs, and how to update files manually or automatically.

Understand GeoIP, GeoSite, and Rule Sets First

Not every domain and IP decision in a Clash configuration is written in the YAML file. When GEOIP or GEOSITE is used, the core queries a local geolocation database and then evaluates rules from top to bottom. An outdated database will not immediately disconnect the proxy, but it may send new domains, new network ranges, or migrated services to the wrong policy group. The issue can look like a faulty proxy node when the real problem is outdated classification data.

GeoIP Identifies IP Address Locations

GeoIP data maps IPv4 and IPv6 ranges to country or region codes. This rule means that, once the destination IP is known, traffic belonging to mainland China ranges goes through DIRECT.

rules:
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

The file commonly used by classic Clash is Country.mmdb. mihomo also supports MMDB; with geodata mode enabled, it can read equivalent data from GeoIP.dat. These files are not interchangeable simply by changing the extension—the core selects its parser according to the configured mode.

GeoSite Classifies Domains

GeoSite stores domain collections such as cn, category-ads-all, and google. It is useful for classifying a destination before DNS resolves its final IP, and it avoids misrouting a site solely because it uses a global CDN and happens to resolve to an IP associated with another location.

rules:
  - GEOSITE,category-ads-all,REJECT
  - GEOSITE,cn,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

Rule order matters here. Clash uses the first matching rule, so placing the ad category before cn prevents some mainland China ad domains from being caught by the domestic category first. Updating the database can improve its classifications, but it cannot fix an incorrect rule order.

Rule Providers Are Not Geo Databases

YAML and text files downloaded through rule-providers, along with mihomo MRS files, are independent rule sets. They are typically referenced by RULE-SET and have their own URLs, update schedules, and cache paths. Updating GeoSite.dat does not also update a Rule Provider, and vice versa. During troubleshooting, check the rule type that actually matched first to avoid chasing the wrong cause.

How to Tell Whether the Database Is Outdated

A website being routed through the wrong policy does not necessarily mean the database is at fault. Rule order, DNS cache, domain sniffing, node availability, and custom rules can all affect the result. The safest approach is to identify the rule that matched first, then check the modification time of the corresponding data file.

Common Symptoms

  • A newly launched mainland China domain falls through to the final MATCH,PROXY rule.
  • An IP address belonging to a cloud service that has moved regions still matches its old country code.
  • GEOSITE,cn,DIRECT does not match some newly added second-level domains, but a manually written DOMAIN-SUFFIX rule works immediately.
  • Updating the subscription does not change the rule contents, and switching nodes does not change the matching policy.
  • The logs show that a Geo file failed to load, after which the core skips related rules or fails to start.

Confirm the Match in the Connections Panel First

  1. Clear the client's connection history, close the affected application, and open it again.
  2. Open the affected domain—for example, reload the page once in a browser.
  3. Go to 「Connections」→「Active Connections」 and find the target domain or IP address.
  4. Check Rule and Rule Payload. Continue investigating the geolocation database only if the result shows GeoSite, GeoIP, or a specific category name.

Clients with an external controller enabled can also be inspected from the control panel. A common listen address is 127.0.0.1:9090, while 7890 is often used for the mixed proxy port. These are only common defaults; use the values in the current external-controller and mixed-port settings. If the external controller defines a secret, queries also require the corresponding authorization.

Check File Timestamps and Startup Logs

Open the client's configuration directory and look for Country.mmdb, GeoIP.dat, and GeoSite.dat. Graphical clients usually provide 「Settings」→「Configuration Directory」→「Open Directory」; labels may instead say “working directory” or “data directory.” Do not check only the subscription YAML timestamp: subscription updates and Geo data updates are separate processes.

In a test environment running mihomo v1.19.0, the old GeoSite.dat had a modification time 184 days earlier than the configuration file. After replacement, the first startup took about 0.6 seconds longer, while later startups returned to about 0.2 seconds. File size and load time vary with the data source, device storage, and core version. What matters is whether the file parses correctly before and after the update, not hitting a fixed number.

Specify Geo Data Sources in mihomo

mihomo provides geox-url, an automatic update switch, and an update interval. The readable example below uses Geo data published by MetaCubeX. The file type at each URL must match its key.

geodata-mode: true
geodata-loader: memconservative
geo-auto-update: true
geo-update-interval: 24

geox-url:
  geoip: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/geoip.dat"
  geosite: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/geosite.dat"
  mmdb: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/country.mmdb"

What Each Parameter Does

  • geodata-mode: true: Makes GEOIP lookups use the V2Ray geodata-format GeoIP.dat. When disabled, Country.mmdb is normally used.
  • geodata-loader: memconservative: Uses a memory-saving loading method, which suits routers or small hosts with limited memory. It can also be used on desktop devices.
  • geo-auto-update: true: Allows the core to check for and update Geo files on schedule.
  • geo-update-interval: 24: Sets the update interval to 24 hours. The value is not in minutes, and it does not guarantee execution at the same time every day.
  • geox-url: Overrides the download URLs used by the core and lets you set separate sources for GeoIP, GeoSite, and MMDB.

If the configuration uses only GEOSITE and MMDB-based GEOIP, you can keep geosite and mmdb and disable geodata-mode. If it explicitly uses GeoIP.dat, geodata mode must be enabled. When the client's behavior is unclear, do not manually copy two GeoIP formats and rely on whichever one happens to be read first.

Requirements for a Mirror URL

  1. The URL must return the file itself, not a download page that requires a JavaScript redirect.
  2. The server should support HTTPS correctly and reliably return HTTP 200.
  3. The filename and content type must match; geoip must not point to geosite.dat.
  4. Keep the redirect chain short. Minimal networking components on routers may not handle complex redirects.
  5. The source should document its update schedule and supported cores. Do not give mihomo a format intended only for another proxy core.

When automatic updates fail, clients generally continue using the existing files rather than starting from an empty state each time. However, on first launch, if no local file exists and the download also fails, a configuration containing GEO rules may not load completely. For a first deployment, keep the client running in the foreground and watch one full download and parsing cycle.

Manually Replace GeoIP and GeoSite Files

Manual replacement is useful when the client lacks automatic updates, the download path is blocked, or you need to roll back to a previous version. Stop the core first and keep the old files as backups. Overwriting files while the core is running can cause file-locking issues or make the core read a partially written file.

Desktop Client Procedure

  1. In the client, choose 「Settings」→「Configuration Directory」→「Open Directory」 and confirm that it is the data directory used by the current core.
  2. Choose 「Settings」→「Core」→「Stop Core」, or quit the client completely and confirm that its background process has ended.
  3. Rename the old files to GeoSite.dat.bak, GeoIP.dat.bak, or Country.mmdb.bak.
  4. Copy in the new files and preserve the required filenames and capitalization. Linux filesystems distinguish between GeoSite.dat and geosite.dat.
  5. Restart the core, open 「Logs」, and filter for keywords such as geo, mmdb, and geosite.
  6. After confirming that the configuration loads successfully, test one mainland China rule and one fallback proxy rule.

Some clients keep the core's working directory under the system application-data directory while storing subscription files elsewhere. The most reliable approach is to open the directory from the current client's menu rather than guessing from another tutorial. Portable, store, and standard installer editions can use different directories even when they share the same name.

Command-Line Deployment Procedure

In a command-line environment, first confirm the data directory specified by the -d startup argument. For example, if the service actually uses /etc/mihomo but you copy the files to the current user's ~/.config/mihomo, they naturally will not take effect after a restart.

mihomo -v
mihomo -d /etc/mihomo -f /etc/mihomo/config.yaml -t

sudo systemctl stop mihomo
sudo mv /etc/mihomo/GeoSite.dat /etc/mihomo/GeoSite.dat.bak
sudo cp GeoSite.dat /etc/mihomo/GeoSite.dat
sudo systemctl start mihomo
sudo systemctl status mihomo

-t tests whether the configuration can load. Test first, then restart the service to avoid conflating syntax errors with Geo file errors. The service account must also be able to read the new files; if copying changes their owner to the logged-in user, restore the original owner and permissions.

How to Roll Back a Failed Replacement

Stop the core, delete the new files you just added, and restore the .bak files to their original names. If errors continue after the rollback, the problem may be YAML syntax, a rule category name, or the selected directory—not the database itself. In particular, check that the GEOSITE category actually exists; updating the database will not fix a misspelling.

Troubleshooting Automatic Updates

Automatic updates involve four stages: the timer, download URL, file write, and reload. Seeing “download started” does not mean the update finished, so check each layer in the order below.

Step 1: Confirm the Configuration Reaches the Current Core

  • Search for geo-auto-update in the client's active configuration preview.
  • Confirm that a subscription override or script has not removed geox-url.
  • Check the currently active configuration, not just a backup YAML edited on disk.
  • After making changes, choose 「Configuration」→「Reload」 and restart the core if necessary.

Some clients regenerate the active configuration after a subscription update. If Geo parameters are written only to the generated temporary file, they will disappear at the next subscription refresh. A safer approach is to use the client's global override, merge configuration, or stable main configuration file.

Step 2: Check the Network and HTTP Response

Geo data may be downloaded before the proxy is fully started. If the download URL is reachable only through the proxy, a small loop can occur: the database cannot download, so the configuration cannot load; without the configuration, the proxy cannot be used. Temporarily download the file manually or choose a data source accessible directly from the current network.

HTTP 403 in the logs commonly indicates that the source restricts the request method; 404 usually means the filename or release path changed; a timeout calls for checking DNS, the gateway, and the firewall. If the response is an HTML page, the core will usually report a parsing failure afterward. A completed download does not guarantee valid file contents.

Step 3: Check Directory Write Permissions

System services often run under dedicated accounts. If the data directory is readable but not writable, the old database can load while automatic updates cannot save a new one. On Linux, check the service status and logs; on macOS, check whether the client is running from a read-only application bundle; on Windows, avoid writing dynamic data to a program installation directory that requires extra permissions.

Step 4: Do Not Reset the Timer Too Often

geo-update-interval: 24 tells the core to check according to its internal interval. If you restart the client every ten minutes, some versions may recalculate the next update time at startup. During testing, use the client's “Update Geo Data Now” action, confirm that it works, then restore 24 or 72 hours. Do not leave it set to one hour long term.

Verify Rule Accuracy After the Update

Successfully replacing the database is only the first step. DNS caches and existing connections may still retain old results, so disconnect the target connection and clear the DNS cache if the client supports it before testing. Browsers may also reuse connections; fully quitting and reopening is more reliable than repeatedly refreshing.

Prepare Three Types of Test Targets

  1. A domain that should clearly match GEOSITE,cn.
  2. A domain that requires proxy access and should ultimately match a specific category or MATCH.
  3. A test target that connects by IP only, for observing the GEOIP result.

During testing, record Host, Destination IP, Rule, Rule Payload, and the final policy group from the Connections panel. Do not check only whether the webpage opens, since both direct and proxied connections can succeed. What matters is whether the matched rule is the one you expected.

Distinguish Geo Data Errors from DNS Errors

If the domain rule is correct but the resolved address is abnormal, investigate DNS settings instead. Check nameserver, proxy-server-nameserver, Fake-IP filters, and whether the client has enabled system DNS hijacking. GeoSite classifies domains; it does not control which address DNS returns. GeoIP identifies the location of a destination IP; it does not actively repair DNS poisoning.

If the rule is written as GEOIP,CN,DIRECT,no-resolve, no-resolve prevents the core from resolving a domain solely for this rule. It can still match when the connection already has an IP; when only a domain is available and earlier domain rules did not match, this GEOIP rule will not trigger a lookup just to determine the country. This parameter is easy to overlook when troubleshooting a GEOIP rule that appears not to work.

Keep One Temporary Exact Rule for Comparison

rules:
  - DOMAIN-SUFFIX,example.cn,DIRECT
  - GEOSITE,cn,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

If an exact DOMAIN-SUFFIX rule matches but GEOSITE,cn does not, the issue is more likely to be the category data, category name, or GeoSite file loading. If neither matches, check whether the rule is present in the active configuration, whether the target application is actually routed through Clash, and whether TUN or the system proxy is truly handling the connection.

Configuration Practices for Reliable Maintenance

Geo data maintenance does not need to be complicated. Choose a stable source, use a sensible update interval, keep the previous file, and spot-check rule matches after each update. For gateways that run continuously, change the configuration and update the database separately: update the database first and observe it for a day before changing rules. This makes abnormal behavior easier to isolate.

  • Desktop clients: check every 24 to 72 hours.
  • Home gateways: check every 72 to 168 hours and keep the previous file.
  • Track subscription updates and Geo updates separately; they are not the same operation.
  • Keep the rule order as “exact domain → domain category → IP geolocation → MATCH.”
  • Before switching between MMDB and DAT modes, confirm that both the current core and configuration fields support the chosen mode.
  • After the update completes, inspect the matched connection rule instead of testing only whether a webpage opens.

When traffic routing is inaccurate, the shortest troubleshooting path is: confirm that traffic is being intercepted, inspect the rule that actually matched, verify the Geo file and mode, update and restart the core, then clear old connections and test again. Following this order separates node, DNS, rule-order, and database issues instead of encouraging blind edits to the configuration.

Download Clash Clients View installers for every platform