YunaiV/yudao-cloud · error · RuntimeException

AreaUtils 初始化失败

Error message

AreaUtils 初始化失败

What it means

AreaUtils statically loads china-area CSV data (areas + parent/child links) from the classpath in a static initializer. Any failure — missing resource, malformed CSV row, Integer.parseInt on a bad code, or the Assert '父子节点相同' (area is its own parent) — is wrapped in RuntimeException('AreaUtils 初始化失败'). The exception type loses the detail; the cause carries it.

Source

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

            // 从 csv 中加载数据
            List<CsvRow> rows = CsvUtil.getReader().read(ResourceUtil.getUtf8Reader("area.csv")).getRows();
            rows.remove(0); // 删除 header
            for (CsvRow row : rows) {
                Area area = new Area(Integer.valueOf(row.get(0)), row.get(1), Integer.valueOf(row.get(2)), null, new ArrayList<>());
                areas.put(area.getId(), area);
            }

            // 构建父子关系：因为 Area 中没有 parentId 字段,所以需要重复读取
            for (CsvRow row : rows) {
                Area area = areas.get(Integer.valueOf(row.get(0))); // 自己
                Area parent = areas.get(Integer.valueOf(row.get(3))); // 父
                Assert.isTrue(area != parent, "{}:父子节点相同", area.getName());
                area.setParent(parent);
                parent.getChildren().add(area);
            }
            log.info("启动加载 AreaUtils 成功，耗时 ({}) 毫秒", System.currentTimeMillis() - now);
        } catch (Exception e) {
            throw new RuntimeException("AreaUtils 初始化失败", e);
        }
    }

    /**
     * 获得指定编号对应的区域
     *
     * @param id 区域编号
     * @return 区域
     */
    public static Area getArea(Integer id) {
        return areas.get(id);
    }

    /**
     * 获得指定区域对应的编号
     *
     * @param pathStr 区域路径，例如说：河南省/石家庄市/新华区
     * @return 区域

View on GitHub (pinned to 477be9dd49)

Solutions

  1. Read getCause() to see the real failure: FileNotFoundException/IOException (missing resource), NumberFormatException (bad id), IllegalArgumentException (parent==self).
  2. Ensure the area CSV resource ships in the jar (check jar tf or target/classes for the resource path).
  3. If the CSV was customized, validate every row: id != parentId and both columns numeric.
  4. Restore the stock resource file if edits corrupted it.
Defensive patterns

Strategy: validation

Validate before calling

// startup smoke check
if (AreaUtils.class.getResource("/area.csv") == null) { // adjust to actual resource path
    throw new IllegalStateException("area CSV resource missing from classpath");
}

Try / catch

try {
    Area area = AreaUtils.getArea(id);
} catch (ExceptionInInitializerError e) {
    Throwable cause = e.getCause(); // RuntimeException with real reason
    log.error("AreaUtils init failed: {}", cause.getCause());
}

Prevention

When it happens

Trigger: First touch of AreaUtils (class loading) in an app where area.csv / csv resource was not packaged (filtered out of the fat jar), or the CSV was hand-edited so column 0 (id) equals column 3 (parentId) for some row, or a row has non-numeric id.

Common situations: Maven shade/assembly excluding resources; a custom-region CSV edit introducing a self-loop or duplicate id; trimming the jar for serverless and accidentally removing the data file; encoding issues (GBK vs UTF-8) breaking column parsing.

Related errors

AI-assisted analysis of YunaiV/yudao-cloud@477be9dd49 (2026-08-14). Data as JSON: /api/errors/55f0f1198b2e6d85. Report an issue: GitHub.