#Updating GeoIP & GeoSite Databases: File Locations, Auto-Update Config, and Error Fixes

##What GeoIP and GeoSite Each Solve

Anyone who's written routing rules has probably seen these two lines:

GEOIP,CN,DIRECT
RULE-SET,geosite-cn,DIRECT

The first line determines region by IP address; the second determines site ownership by a domain list. Behind these two rule types sit two different data files, and understanding the difference is the first step in troubleshooting inactive rules.

geoip.metadb is a mapping table from IP address ranges to country codes, stored in the MMDB binary format. When a rule reads GEOIP,CN,DIRECT, the mihomo core looks up the connection's destination IP in this table, and if the country code comes back as CN, the direct rule matches. This table covers IPv4 and IPv6 address block assignments and has no direct relationship to domain names — the IP a given domain resolves to might be inside mainland China today and switch to a server outside China tomorrow, which is part of why pure IP-based matching occasionally "drifts."

geosite.dat is a domain list organized by category, compressed in Protobuf format, with common categories like cn, google, netflix, and category-ads-all. The typical syntax declares a geosite-based rule set under rule-providers and then references it under rules, though some cores also support the shorthand GEOSITE,cn,DIRECT. Domain matching happens before DNS resolution or before the request is sent, based on the domain string itself rather than the resolved result — so for CDN-hosted sites whose IPs change frequently, geosite tends to be more stable than geoip.

Using both together is common practice: match by geosite where the domain is recognized, and fall back to geoip for the remaining traffic based on the destination IP's region. If either file is missing or outdated, the corresponding rule type fails silently rather than throwing an error — which is exactly why this class of problem is easy to miss.

##Where the Database Files Are Stored

The mihomo core checks for these two files in a fixed order at startup — understanding that lookup logic is more useful than memorizing one path.

1. The core's working directory (Home Dir) comes first. Most GUI clients assign the core a dedicated working directory, and geoip.metadb, geosite.dat, and country.mmdb (some versions use this filename instead of geoip.metadb) get downloaded to the root of that directory, sitting alongside config.yaml rather than scattered into subfolders.
2. The folder containing the config file comes next. If no separate working directory is specified, the core falls back to the folder holding the current config file to look for these two files, and only triggers a first-time download if they're not found there.
3. System-level default paths act as the final fallback. On Linux this is commonly ~/.config/clash/ or ~/.config/mihomo/; on Windows it's usually a data subfolder inside the client's install directory; on macOS it's typically the client's Application Support folder. Naming for this fallback location varies between clients, so if a file seems missing, checking the client's "Settings" or "About" page for the actual working directory path is faster than hunting through the filesystem.

Once you've confirmed the path, checking the file's modification timestamp directly is the most straightforward way to tell whether a database is "stale" — far more reliable than repeatedly restarting the client and guessing.

##Writing geodata-mode and geo-auto-update

Whether geo databases are enabled and how often they're auto-checked for updates is controlled by a handful of fields in config.yaml. A typical setup looks like this:

geodata-mode: true
geodata-loader: standard
geo-auto-update: true
geo-update-interval: 24
geox-url:
  geoip: "https://github.com/MetaCubeX/meta-rules-dat/releases/latest/download/geoip.metadb"
  geosite: "https://github.com/MetaCubeX/meta-rules-dat/releases/latest/download/geosite.dat"
  mmdb: "https://github.com/MetaCubeX/meta-rules-dat/releases/latest/download/country.mmdb"

What each field means:

• geodata-mode: whether geo database-based matching is enabled. When set to false, GEOIP and geosite rules won't load — writing them in the rule file has no effect, they're treated as empty rules. Keep this true unless you're certain you don't need geo rules.
• geodata-loader: the database loading strategy. standard loads the full database into memory, giving fast lookups at slightly higher memory cost; some versions offer a low-memory mode like memconservative, useful for resource-constrained router hardware.
• geo-auto-update: whether the core automatically checks for database updates while running. The default (on or off) varies by client version, so it's worth confirming the current value manually.
• geo-update-interval: the auto-check interval, in hours. Setting this too short generates unnecessary network requests — 24 to 72 hours is generally a reasonable range.
• geox-url: the download source for each of the three files. If the default source is slow on your network, you can swap in a mirror from the same project, but make sure the file content and format version match — mixing rule databases from different projects tends to cause parsing failures.

Note that geo-auto-update only matters while the core keeps running continuously — if the client shuts down the core process every time it exits, whether an update check happens again on next launch depends on the client's own startup flow, not purely on this field's behavior.

##Manual Update Steps

Most GUI clients don't require touching the config file by hand — the update option is usually in the settings page, typically a button labeled "Update GeoIP Database" or "Update Geo Data." Clicking it makes the client call an API exposed by the core to trigger the download, taking anywhere from a few seconds to under a minute depending on network conditions.

If your client doesn't offer a GUI option, or you want to confirm an update actually took effect, follow these steps:

1. Confirm the core's RESTful API port and secret key (usually found under the external-controller and secret fields in config.yaml) — these are required to call the core's API.
2. Trigger the update through the API. A typical request sends an update command to the core's /configs/geo endpoint (the exact path may vary slightly by version), so check the API docs for the specific core version you're using.
3. After the update finishes, check the client or core logs for a message like "GeoIP database update completed" or a clear download-success indicator — don't assume success just because nothing errored on screen.
4. Restart the core or client once so rules reload against the newly updated database files. In some cases the update completes but the rule matcher doesn't hot-reload, and a restart is the safest way to ensure it takes effect.

If you genuinely can't find an automated option, manually downloading and swapping the files works too: grab the latest geoip.metadb and geosite.dat from the database source repository's Releases page, replace the old files in the working directory, then restart the core. It's worth backing up the old files first, so you can roll back immediately if the new ones turn out corrupted or in an incompatible format.

##Common Errors and Troubleshooting Inactive Rules

Most of these issues don't throw an obvious error — they just show up as "the rule doesn't seem to be working." Checking things in the order below is far more efficient than guessing at random.

Download fails or times out

Log messages mentioning connection timeouts or TLS handshake failures usually point to a network path issue — if the proxy hasn't connected yet, the core's direct connection to the download source may itself be blocked by your network environment. Try switching the geox-url addresses to a mirror source, or trigger the update manually again once the proxy connection is already established.

File downloaded, but rules still don't match

First confirm whether geodata-mode is set to true — this is the most commonly overlooked item. Then check whether the region code or category name written in the rule actually exists in the current database version. Category names like geosite-cn can get renamed or split across versions of different rule set projects, and copying an old config as-is is a common way to hit this trap.

Rule set fails to load with "rule provider not found" or a format error

This is often caused by a mismatch between the behavior field in rule-providers and the actual file format. geosite-based rule sets should use behavior: domain, while IP-range-based rule sets should use behavior: ipcidr. Getting these reversed makes the core unable to parse the file content correctly, resulting in a format error.

rule-providers:
  geosite-cn:
    type: http
    behavior: domain
    url: "https://example.com/geosite-cn.txt"
    path: ./rule-providers/geosite-cn.yaml
    interval: 86400

No change in behavior after updating

Confirm whether the update actually replaced the file at the correct path — if the folder holding the client's config file isn't the same as the core's actual working directory, the update script may write to one location while the core reads from another, which shows up as "updated, but nothing changed." Going back to the second section to re-check path priority usually pinpoints the issue.

Working through these categories in order will generally point you to one of four root causes — network, config field, file path, or rule set format — so you can address it directly, without needing to reinstall the client or rewrite the entire config file.