YunaiV/ruoyi-vue-pro · critical · RuntimeException

IPUtils 初始化失败

Error message

IPUtils 初始化失败

What it means

IPUtils statically loads the ip2region.xdb binary into a Searcher. If ResourceUtil.readBytes('ip2region.xdb') fails (resource missing) or Searcher.newWithBuffer throws (corrupt/unsupported xdb format), init() wraps the cause as RuntimeException('IPUtils 初始化失败'). The SEARCHER field stays null, so any later getAreaId would NPE, hence fail-fast at class load.

Source

Thrown at yudao-framework/yudao-spring-boot-starter-biz-ip/src/main/java/cn/iocoder/yudao/framework/ip/core/utils/IPUtils.java:40

     * IP 查询器，启动加载到内存中
     */
    private static Searcher SEARCHER;

    static {
        init();
    }

    /**
     * 初始化
     */
    private static void init() {
        try {
            long now = System.currentTimeMillis();
            byte[] bytes = ResourceUtil.readBytes("ip2region.xdb");
            SEARCHER = Searcher.newWithBuffer(bytes);
            log.info("启动加载 IPUtils 成功，耗时 ({}) 毫秒", System.currentTimeMillis() - now);
        } catch (Exception e) {
            throw new RuntimeException("IPUtils 初始化失败", e);
        }
    }

    /**
     * 查询 IP 对应的地区编号
     *
     * @param ip IP 地址，格式为 127.0.0.1
     * @return 地区id
     */
    @SneakyThrows
    public static Integer getAreaId(String ip) {
        return Integer.parseInt(SEARCHER.search(ip.trim()));
    }

    /**
     * 查询 IP 对应的地区编号
     *
     * @param ip IP 地址的时间戳，格式参考{@link Searcher#checkIP(String)} 的返回

View on GitHub (pinned to 0418084e22)

Solutions

  1. Confirm ip2region.xdb is present in the classpath (inspect the built jar).
  2. Exclude the .xdb from Maven resource filtering (binary filtering corrupts it): add <nonFilteredFileExtensions>xdb</nonFilteredFileExtensions>.
  3. Re-download a known-good ip2region.xdb if it is corrupt.
  4. Pin a compatible ip2region SDK version matching the xdb format.

Example fix

// before: resource filtering corrupts the binary
// pom.xml (spring-boot): resources with filtering on all
// after: exclude binary from filtering
<plugin>
  <artifactId>maven-resources-plugin</artifactId>
  <configuration>
    <nonFilteredFileExtensions>xdb</nonFilteredFileExtensions>
  </configuration>
</plugin>
Defensive patterns

Strategy: try-catch

Validate before calling

if (getClass().getClassLoader().getResource("ip2region.xdb") == null)
    throw new IllegalStateException("ip2region.xdb missing from classpath");

Type guard

null

Try / catch

try { IPUtils.getAreaId(ip); }
catch (RuntimeException e) { if (e.getMessage().contains("IPUtils")) { /* return unknown region */ } throw e; }

Prevention

When it happens

Trigger: ip2region.xdb is not packaged into the classpath (maven resource filtering/shading dropped it); the xdb file is corrupt or truncated; an incompatible ip2region version that rejects the buffer format.

Common situations: Shaded jar missing the .xdb; resource path case mismatch on case-sensitive FS; building on a platform that mangles the binary during filtering.

Related errors

AI-assisted analysis of YunaiV/ruoyi-vue-pro@0418084e22 (2026-08-14). Data as JSON: /api/errors/b8da192dda5af69f. Report an issue: GitHub.