What causes "注册用户资源目录的xml文件失败" in baomidou/mybatis-plus?

Check the wrapped IOException cause for which classpath entry failed to read; fix permissions or remove the offending jar/layout

baomidou/mybatis-plus · error · RuntimeException

注册用户资源目录的xml文件失败

Error message

注册用户资源目录的xml文件失败

What it means

Thrown by MyBaitsRuntimeHintsRegistrar (note the 'MyBaits' typo in the class name) in mybatis-plus-spring-boot-native-image: during GraalVM native-image AOT processing it scans the classpath for mapper XML resources via AotUtils.findResources and, on IOException, wraps it in RuntimeException('注册用户资源目录的xml文件失败' — failed to register xml files from user resource directories). It prevents building a native image whose resource hints would silently miss mapper XMLs.

Source

Thrown at spring-boot-starter/mybatis-plus-spring-boot-native-image/src/main/java/com/baomidou/mybatisplus/aot/MyBaitsRuntimeHintsRegistrar.java:42

 * mybatis aot 运行时提示注册器
 *
 * @author xiaochen
 * @since 2026-01-12
 */
class MyBaitsRuntimeHintsRegistrar implements RuntimeHintsRegistrar {

    @Override
    public void registerHints(RuntimeHints hints, ClassLoader classLoader) {
        AotUtils aotUtils = new AotUtils(hints, classLoader);
        registerXml(aotUtils);
    }

    private void registerXml(AotUtils aotUtils) {
        try {
            aotUtils.registerPattern(aotUtils.findResources("",
                CollectUtils::isMapperXmlResource).toArray(AotUtils.EMPTY_STRING_ARRAY));
        } catch (IOException e) {
            throw new RuntimeException("注册用户资源目录的xml文件失败", e);
        }
    }

}

View on GitHub (pinned to bf67d90747)

Solutions

Check the wrapped IOException cause for which classpath entry failed to read; fix permissions or remove the offending jar/layout
Simplify the classpath for the native compile step (unpack/standard layout) so classloader resource traversal works
Ensure mapper XMLs are under standard/src/main/resources locations matched by the scan rather than generated in unusual places
If custom resource locations are needed, declare them explicitly via standard GraalVM resource hints (resource-config / @ImportRuntimeHints) instead of relying only on the scan

Defensive patterns

Strategy: try-catch

Validate before calling

// Before native compile, confirm mapper XMLs are discoverable as classpath resources
Enumeration<URL> urls = getClass().getClassLoader().getResources("mapper");
while (urls.hasMoreElements()) {
    URL u = urls.nextElement();
    if (!"file".equals(u.getProtocol()) && !"jar".equals(u.getProtocol())) {
        throw new IllegalStateException("Unsupported classpath protocol: " + u);
    }
}

Try / catch

try {
    // native-image compile / AOT process run
} catch (RuntimeException e) {
    if ("注册用户资源目录的xml文件失败".equals(e.getMessage())) {
        throw new IllegalStateException("AOT resource scan failed; check classpath readability", e.getCause());
    }
    throw e;
}

Prevention

Keep mapper XMLs in the application's own resources, not nested/shaded jars
Declare mapper patterns explicitly in GraalVM resource-config as a belt-and-braces measure
Run the AOT processing goal in CI early so classpath issues surface before full native compilation

When it happens

Trigger: Compiling a Spring Boot app to a GraalVM native image with this module on the classpath, when the resource scan (classpath traversal for files matching CollectUtils.isMapperXmlResource) throws IOException — e.g. unreadable jars, exotic classloader schemes, or filesystem issues during native-image compilation.

Common situations: First native-image build of a MyBatis-Plus app; classpath containing jars in non-standard locations (fat jars, custom loaders); CI environments with restricted filesystem permissions; after upgrading Spring Boot AOT APIs.

Related errors

AI-assisted analysis of baomidou/mybatis-plus@bf67d90747 (2026-08-14). Data as JSON: /api/errors/7da5c3fa320e7145. Report an issue: GitHub.