How to Update GeoIP and GeoSite Databases: mihomo Rule Data Maintenance and Common Errors

GeoIP and GeoSiteWhat Problems Do They Solve?

When mihomo evaluates proxy rules, it compares the domain name, IP address, or other connection attributes with each rule in order. GeoIP and GeoSite both provide data used for rule evaluation, but they work with different inputs. An outdated database does not necessarily interrupt every proxied connection; more often, location classification becomes stale, new domains fail to match, or startup reports that a data file is missing.

GeoIP classifies the region associated with the destination IP

GeoIP data maps IP address ranges to countries, regions, and related information. In a configuration, GEOIP,CN,DIRECT means that once the destination IP is known, connections whose address belongs to the CN category use the DIRECT policy. Common files include Country.mmdb and geoip.dat; which one mihomo reads depends on the configuration, client version, and data mode.

GeoIP operates at the IP layer. If the domain resolves to the wrong address, DNS results are polluted, or an earlier domain rule has already matched, a later GEOIP rule cannot change the completed match. So when a mainland China website is sent through the proxy, do not look only at the database date; also check rule order and DNS results.

GeoSite classifies domain-name collections

GeoSite stores curated domain-name collections. For example, GEOSITE,cn,DIRECT matches domains in the cn category, while GEOSITE,category-ads-all,REJECT can handle the corresponding category. The common data file is geosite.dat. GeoSite does not determine which country hosts a server IP; it works directly with the domain in the request.

After a domain service adds an endpoint, changes its CDN domains, or replaces an API, an older GeoSite database may not contain the relevant entry. The connection will usually fall through to a later rule such as MATCH, rather than showing a “database expired” message. That is why GeoSite issues are often mistaken for node or subscription failures.

Confirm the kernel, mode, and actual data directory before updating

The same desktop client may have used the Clash Premium, Clash Meta, or mihomo kernel at different times. Multiple files with the same name may also remain in an old configuration directory. Before replacing anything manually, confirm the active kernel in the client’s “About,” “Kernel,” or “Runtime Log” screen. A maintained stable release of mihomo is recommended; record the kernel version and data-file modification times before updating.

Determine the directory from the startup arguments

mihomo’s data directory is typically specified by the -d startup argument. For example, if the command includes mihomo -d /home/user/.config/mihomo, the databases belong in that directory, not beside the executable. Desktop clients pass their own data directory to the kernel, so the path cannot be inferred from the operating system alone.

• Use the client’s “Settings” → “Configuration Directory” or “Open Data Directory” option whenever possible.
• If the interface provides no such option, look near the start of the runtime log for configuration directory, home directory, or the path following -d.
• On Windows, confirm the executable in the process details of Task Manager, then inspect the client log for its startup arguments.
• On macOS, client data is usually stored in the user’s Library, but each app may use a different container directory. Follow the log and the client’s directory shortcut.
• When a Linux service is started by systemd, use systemctl cat mihomo to inspect the ExecStart line and its -d argument.

Confirm whether the active format is MMDB or DAT

mihomo supports multiple geographic data formats. When geodata-mode: true is enabled, it usually works with geoip.dat and geosite.dat; without that mode, the configuration may use Country.mmdb for GEOIP matching. Defaults can change between versions, so check both the configuration and startup log instead of inferring the mode from file presence alone.

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

geo-update-interval is measured in hours. Setting it to 24 tells the kernel to check for data updates once a day. If the client generates the runtime configuration, direct edits to that generated file may be overwritten on the next launch or subscription switch. Add these keys in the client’s override, Mixin, or global extension configuration instead.

Prefer the client’s built-in updater

Clients that support mihomo usually offer a GeoData or geographic-data update option. Labels vary by version; common paths include “Settings” → “Clash Settings” → “GeoData” or “Settings” → “Kernel” → “Update Geographic Data.” Do not click repeatedly. A single download may contain tens of megabytes, so on a slow connection wait for the log to report completion.

1. Update and enable the current configuration first, then confirm that the kernel starts normally.
2. Open the GeoData, geographic data, or kernel data page under “Settings.”
3. Run the GeoIP, GeoSite, or full update separately.
4. Wait for the interface to report completion, then check the log for messages such as download, unmarshal, or permission denied.
5. Reload the configuration. If the client has no reload button, quit the application completely and start it again.
6. Use the connection log to see which rule actually matched a known domain.

The advantage of a built-in updater is that the client knows its own data directory and can write the downloaded file under the correct name. For desktop clients using service mode or an administrator-assisted background process, it can also avoid write-permission problems for the normal user process.

Enable mihomo automatic updates

For routers, servers, or desktop devices that run continuously, mihomo can update the data on a schedule. In addition to enabling geo-auto-update, use geox-url to specify a URL for each file type. Each URL must return the binary file directly; it must not return a release page or an HTML page that requires browser confirmation.

geodata-mode: true
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"

If the device needs a proxy to reach the download URL, first ensure that the kernel can establish an outbound connection after startup. On the first launch, the database may not exist while rules already depend on GeoSite, creating a loop: the kernel cannot start without the database, and the database cannot be downloaded without the kernel. In that case, place readable data files manually first, then enable automatic updates.

Manually replace GeoIP and GeoSite files

Manual replacement is useful when the client’s built-in updater fails, an offline device needs maintenance, or the current network cannot reach the data source. Do not overwrite a file that is being read. Download to a temporary name, stop the kernel, replace the file, and start it again. This reduces the chance of leaving a partially downloaded file behind.

General replacement procedure

1. Disable the system proxy and TUN in the client, then quit the application. In service mode, stop the corresponding background service as well.
2. Open the data directory identified earlier and record the original files’ sizes and modification times.
3. Rename the old files to geoip.dat.bak, geosite.dat.bak, or Country.mmdb.bak.
4. Copy the new files into the same directory, preserving the exact filenames required by the kernel.
5. Check that the current user or service account has read permission.
6. Start the client and inspect the earliest part of the log. Only enable the system proxy or TUN after confirming that configuration loading has completed.
7. Keep the backups until verification is complete, then delete them after common domain rules work normally.

On Linux or macOS, write to a temporary file first, then replace the target with a rename on the same filesystem. Run the following commands in mihomo’s actual data directory:

curl -L "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/geoip.dat" -o geoip.dat.new
curl -L "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/geosite.dat" -o geosite.dat.new

mv geoip.dat geoip.dat.bak
mv geosite.dat geosite.dat.bak
mv geoip.dat.new geoip.dat
mv geosite.dat.new geosite.dat

When manually replacing files on Windows, if File Explorer says a file is in use, the kernel process or service may still be running after the client window closes. Stop the service in the client, or use “Task Manager” → “Details” to confirm that the mihomo process has exited. Do not repeatedly overwrite the file to bypass the lock.

Additional checks for containers and routers

For a Docker deployment, confirm that the database directory is actually mounted as a volume at the -d path used inside the container. Replacing a similarly named, unmounted directory on the host will not change the container. After updating, restart the container and confirm the read path in the log. On space-constrained devices such as OpenWrt routers, check available storage as well; a temporary download plus backups can briefly consume nearly two or three times the size of the data files.

How to handle download failures and startup errors

context deadline exceeded or TLS timeout

These messages usually mean that the download endpoint did not finish connecting or transferring before the timeout. Test the same URL with a browser or curl -I -L to confirm that redirects work, then check DNS, system time, and outbound policies. A clock difference of only a few minutes can make TLS validation fail. If the connection must use a proxy, verify that the update request uses a working policy instead of being sent to a dead node by a GEOIP or MATCH rule.

403, 404, or an HTML file downloaded instead

A 404 usually means that the filename, release path, or data-source structure has changed. A 403 commonly indicates rate limiting, network egress restrictions, or a URL requiring additional authorization. Another possibility is that the URL points to a release description page and returns HTML instead of the file. mihomo will then report a parse failure, invalid format, or inability to load the database. Switch to a direct file URL and confirm that the redirected response type and file size are reasonable.

permission denied or the file cannot be written

First confirm that the path in the error is the current data directory. In Windows service mode, the interface process and background service may use different accounts; a Linux systemd service may also specify a restricted account with User=. The directory must allow that service account to create temporary files, rename files, and read the updated result. Granting write permission only to an old file may still fail if the directory itself is not writable.

no such file, MMDB will not open, or GeoSite fails to load

First check filename case, configuration mode, and directory. Linux distinguishes GeoSite.dat from geosite.dat. If geodata mode is enabled but only Country.mmdb is present, GeoSite rules still cannot work; conversely, a configuration that relies on MMDB cannot work with only geoip.dat. If restoring a backup allows startup, the new file is usually incomplete, in the wrong format, or incompatible with the current kernel.

The database is updated. Why are the rules still not working?

The rule engine evaluates rules from top to bottom in configuration order and usually stops at the first match rather than searching for a “better” rule. Updating the database only changes the data available to GEOIP or GEOSITE; it does not reorder rules. During troubleshooting, find the target request in the connection log and inspect its domain, destination IP, matched rule, and final policy.

An earlier rule has already intercepted the request

rules:
  - DOMAIN-SUFFIX,example.com,Proxy
  - GEOSITE,cn,DIRECT
  - GEOIP,CN,DIRECT,no-resolve
  - MATCH,Proxy

In this configuration, even if example.com is included in GeoSite’s cn category, the first DOMAIN-SUFFIX rule still matches Proxy. Updating GeoSite does not override earlier rules. Temporarily move the specific rule to the appropriate position and test again after reloading to determine whether rule order is the cause.

no-resolve changes when GEOIP can apply

One purpose of GEOIP,CN,DIRECT,no-resolve is to prevent the rule from triggering an extra DNS lookup just to perform a match. If the current connection has only a domain and no destination IP is available, the rule may not produce the expected result. When the configuration already has GEOSITE domain rules, classify by domain first and use GEOIP for remaining IP connections; the logic is clearer.

DNS mode and sniffing affect the visible domain

In TUN mode, an application may connect directly to an IP, or send requests through QUIC, encrypted DNS, or a built-in resolver. If mihomo does not receive a domain name, GeoSite has no input to match. Domain sniffing can cover some cases, but it is not a guarantee that every connection’s domain can be recovered. Compare connection details in system-proxy and TUN modes to verify whether a complete domain appears in the log.

You edited the subscription source, not the runtime configuration

Desktop clients often merge the subscription, overrides, and global settings into a temporary runtime configuration. Editing a cached subscription YAML directly will be undone at the next subscription update; editing the runtime configuration will disappear when the configuration is switched. Save custom settings under the client’s “Settings” → “Overrides” or “Configuration” → “Global Extensions,” then verify the final result through the log or configuration inspection tool.

The Rule Provider was not updated with GeoData

External rule sets referenced by RULE-SET are managed by rule-providers and have their own URL, cache path, and update interval. Updating geoip.dat and geosite.dat does not refresh these Providers. If the actual match is a RULE-SET, update it from the client’s rule-set page or inspect the Provider’s interval and download log.

A repeatable maintenance checklist

Desktop users generally do not need to replace databases manually every day. A more practical approach is to let the client or mihomo check every 24 hours and follow a fixed diagnostic sequence when classifications look wrong. For servers and routers, include the data directory, backups, and service-account permissions in routine maintenance.

• Confirm that mihomo is the active kernel and record its version.
• Confirm the actual data directory from the startup arguments or log.
• Check whether the configuration uses DAT mode or MMDB mode.
• Run one update through the client’s built-in updater first.
• Review the log to confirm that downloading, writing, and reloading have all completed.
• For manual replacement, stop the kernel first and keep a restorable copy of the old files.
• Use connection logs to verify the domain, destination IP, matched rule, and final policy.
• Check GeoData, subscription rules, and Rule Providers separately; do not treat them as one update.
• If the result is still wrong, check rule order, DNS, TUN, sniffing, and runtime configuration in that order.

Do not judge maintenance success solely by an “Update complete” button. Test at least one GeoSite domain rule, one GEOIP address rule, and one Rule Provider rule separately. The update is properly connected to the path, configuration mode, and mechanism only when the connection log shows the expected rule name and policy and the result remains consistent after restarting the client.