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

> Troubleshoot GeoIP lookup failures impacting target applications. Learn to resolve common issues like corrupted files, incorrect flags, and misconfigurations using Loyalsoldier GeoIP files.

- Repository: [Loyalsoldier/geoip](https://github.com/loyalsoldier/geoip)
- Tags: how-to-guide
- Published: 2026-03-06

---

**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`](https://github.com/loyalsoldier/geoip/blob/main/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`](https://github.com/loyalsoldier/geoip/blob/main/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`](https://github.com/loyalsoldier/geoip/blob/main/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`](https://github.com/loyalsoldier/geoip/blob/main/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:

```bash

# 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`](https://github.com/loyalsoldier/geoip/blob/main/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`](https://github.com/loyalsoldier/geoip/blob/main/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`](https://github.com/loyalsoldier/geoip/blob/main/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`](https://github.com/loyalsoldier/geoip/blob/main/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`](https://github.com/loyalsoldier/geoip/blob/main/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`](https://github.com/loyalsoldier/geoip/blob/main/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.