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.

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>

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

null

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

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

• AreaUtils 初始化失败
• 400
• 423
• 429
• 900

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

Appendix: 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)