How to Troubleshoot GeoIP Lookup Failures in Target Applications Using Loyalsoldier GeoIP Files

The most common causes of GeoIP lookup failures are corrupted generated files, incorrect CLI format flags, list priority conflicts in the container engine, or misconfigured application paths; verify your files with geoip lookup and check overwriteList settings to resolve them.

When target applications like V2Ray, mihomo, Clash, or Surge fail to resolve IPs to the expected GeoIP lists, the issue typically stems from one of four layers: file generation, CLI validation, container priority logic, or application integration. This guide walks you through systematic GeoIP lookup failures troubleshooting using the loyalsoldier/geoip source code, covering verification steps from the generated binary files down to the container's Lookup implementation in lib/container.go.

Verify the Generated GeoIP File Integrity

Start by confirming the generated file matches your target application's expected format and contains valid data.

Confirm the file format. The file must match the format specified in your application configuration, such as text, v2rayGeoIPDat, maxmindMMDB, mihomoMRS, or singboxSRS. Run geoip list to enumerate all supported formats as implemented in the CLI.

Check the checksum. Compare the file's SHA256 hash against the published release assets. A mismatched checksum indicates a truncated or corrupted download that will cause lookup failures.

Inspect the content. For text-based files, verify each line follows valid IP or CIDR syntax. For binary formats like geoip.dat or .mmdb, use the geoip lookup command in one-time mode to confirm the list is recognized (see the CLI validation section below).

Validate the CLI Lookup Command

Use the lookup command to isolate whether the failure originates in the file itself or the application layer. This command is defined in lookup.go and orchestrates the lookup via lib.NewInstance.

Understand the critical flags to avoid common pitfalls:

• -f / --format: Specifies the input format (e.g., text, v2rayGeoIPDat). Misspelling this triggers the "unsupported input format" error from supportedInputFormats (see lookup.go lines 21-33).
• -u / --uri: Path or URL to the source file. Relative paths must be resolvable by the CLI.
• -d / --dir: Directory containing multiple source files. Omitting this when loading several lists results in empty results.
• --searchlist: Optional comma-separated filter (case-insensitive). Typos here cause the list to be silently ignored.
• Positional argument: The IP or CIDR to lookup, validated by the special.Lookup converter in plugin/special/lookup.go (lines 40-44).

Typical failure patterns include:

• Output "false" indicates the address is syntactically valid but not found in any loaded list.
• Error "unsupported input format" means the --format flag does not match any supported type.
• Error "please specify an IP or a CIDR as search target" signals an invalid address format (e.g., 300.0.0.1).

Run a direct lookup against your generated file to verify functionality:

# Verify an IP in a single text list

geoip lookup -f text -u ./cn.txt 1.1.1.1

# Check which lists contain an IP in a v2rayGeoIPDat file

geoip lookup -f v2rayGeoIPDat -u ./geoip.dat 1.0.0.1

Inspect the Container Lookup Engine

If the CLI lookup succeeds but your application still fails, investigate the container's priority logic and IP parsing implementation.

The core lookup logic resides in lib/container.go. The Lookup method (lines 195-225) parses input strings as either a CIDR using netip.ParsePrefix or a plain IP using netip.ParseAddr. It then delegates to the private lookup method (lines 227-267), which iterates over all loaded entries, optionally filters by searchList, and checks containment using netipx.IPSet.

Critical troubleshooting points:

• List priority conflicts. If multiple lists contain the same IP, the later-written list wins according to the README §注意事项 (lines 92-95). Ensure your target list appears last in the output configuration, or use the overwriteList option to force priority.
• Search list filtering. When using --searchlist, the container builds a case-insensitive map (searchMap). Extra whitespace or incorrect casing causes the filter to silently exclude valid matches.

Check Application Integration Settings

Misconfigured application paths or incompatible formats are frequent sources of GeoIP lookup failures.

Application	Expected Configuration	Common Gotchas
V2Ray / Xray	geoip: <url-or-path> pointing to the .dat file	Using outdated URLs that reference previous releases; verify the path matches your generated file exactly.
mihomo	geodata-mode: true and geox-url.geoip pointing to .mmdb or .mrs	Forgetting to enable geodata-mode (defaults to false), causing the application to skip GeoIP resolution.
Clash / Surge	rule-providers.<name>.url set to the generated rule-set	Duplicate list names may be merged based on application-specific precedence rules, hiding your expected list.
sing-box	rule_set with format: binary and URL pointing to .srs	Using format: yaml for a binary SRS file triggers parsing failures.

Enable verbose logging in your target application (e.g., loglevel: debug) and search for messages like "GeoIP load failed", "cannot parse IP", or "list not found" to pinpoint the integration failure.

End-to-End Debugging Workflow

Follow this systematic process to isolate and resolve lookup failures:

1. Regenerate the file using geoip convert with the latest configuration to ensure you are testing current data.

2. Run a direct CLI lookup against the regenerated file to confirm the IP/CIDR exists in the expected list.

3. Inspect application configuration to verify the exact path/URL matches the generated file and that geodata-mode or equivalent is enabled.

4. Check list priority in your conversion config. Add overwriteList: ["<your-list>"] to the output section (see configuration.md) and re-convert if multiple lists contain overlapping IPs.

5. Clear application cache by deleting cached GeoIP data in the application's data directory and restarting the service.

Summary

• Verify file integrity by checking format, checksums, and content validity before testing applications.
• Use geoip lookup with correct --format and --uri flags to isolate file-level issues from application issues.
• Check overwriteList settings in lib/container.go logic when multiple lists contain overlapping IP ranges.
• Validate application configs for correct paths, formats (.dat, .mmdb, .srs), and enabled GeoIP modes.
• Clear caches and regenerate files when checksums mismatch or data appears stale.

Frequently Asked Questions

Why does geoip lookup return "false" for an IP I know should be in the list?

The IP is syntactically valid but not found in the loaded lists according to the lookup method in lib/container.go (lines 227-267). Verify you are using the correct --format flag, the --uri points to the intended file, and that --searchlist (if used) matches the list name exactly without extra whitespace.

How do I fix overlapping IP ranges between multiple GeoIP lists?

Use the overwriteList option in your conversion configuration (documented in configuration.md). When specified, lists appearing earlier in overwriteList take precedence over later entries. After modifying the config, rerun geoip convert and reload the file in your application.

What causes "unsupported input format" errors when running lookup commands?

The --format flag does not match any entry in supportedInputFormats as defined in lookup.go (lines 21-33). Check available formats with geoip list and ensure you use valid identifiers like text, v2rayGeoIPDat, maxmindMMDB, or mihomoMRS exactly as implemented in the source.

Why does my application fail to load GeoIP data even though the CLI lookup works?

The application likely points to a different file path, uses an incorrect format setting (e.g., format: yaml for a binary .srs file in sing-box), or has disabled GeoIP modes (e.g., geodata-mode: false in mihomo). Verify the configuration matches the exact file generated by geoip convert and clear any application-specific GeoIP caches.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}