flowable/flowable-engine · error · UncheckedIOException

Failed to read mapper from

Error message

Failed to read mapper from 

What it means

Thrown (as UncheckedIOException) by FlowableMyBatisResourceHintsRegistrar.registerMapper when an individual MyBatis mapper XML resource cannot be read while deriving reflection/resource hints for AOT compilation. The mapper path is included in the message; the cause is the underlying IOException.

Source

Thrown at modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/aot/FlowableMyBatisResourceHintsRegistrar.java:98

                        reflectionHints.registerType(Map.class, memberCategories);
                    }
                }

                String resultType = statement.getStringAttribute("resultType");
                if (resultType != null) {
                    if (resultType.equals("long")) {
                        reflectionHints.registerType(long.class, memberCategories);
                        reflectionHints.registerType(Long.class, memberCategories);
                    } else if (resultType.equals("string")) {
                        reflectionHints.registerType(String.class, memberCategories);
                    } else if (resultType.equals("map")) {
                        reflectionHints.registerType(HashMap.class, memberCategories);
                    }
                }
            }

        } catch (IOException e) {
            throw new UncheckedIOException("Failed to read mapper from " + mapperPath, e);
        }
    }

    protected static XPathParser createParser(InputStream stream) {
        return new XPathParser(stream, false, null, new XMLMapperEntityResolver());
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Confirm the mapper resource path exists: classLoader.getResource("org/flowable/db/mapping/entity/Job.xml") etc., and fix the path if renamed.
2. Include custom and engine mapper XMLs in the artifact (Maven/Gradle resource config, Spring Boot layers).
3. Register mapper XMLs as native resources so the stream is available at AOT/native runtime.
4. Upgrade/align Flowable modules so built-in mapper paths match the engine version on the classpath.

Example fix

// before
hints.resources().registerPattern("org/flowable/db/mapping/*.xml"); // misses subfolders
// after
hints.resources().registerPattern("org/flowable/db/mapping/**/*.xml");

String mapperPath = mapper.getStringAttribute("resource");
if (classLoader.getResource(mapperPath) == null) throw new IllegalStateException("Mapper resource missing from classpath: " + mapperPath);

try {
  registerMapper(mapperPath, hints, classLoader);
} catch (UncheckedIOException e) {
  if (e.getMessage().startsWith("Failed to read mapper from")) {
    log.error("Cannot read mapper XML: {}", mapperPath, e);
  }
  throw e;
}

When it happens

Trigger: During AOT hint registration, a mapper resource listed in the MyBatis configuration is absent from the classpath or its InputStream cannot be opened/parsed (missing file, corrupted XML stream).

Common situations: Custom mapper XML not packaged into the jar/native image; renamed or moved mapper resources after an engine upgrade; classloader differences in Spring Boot fat jars excluding the mapper files.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Failed to read mappings
• Failed to read resource ${resource}
• Failed to read resource ${resource}
• Failed to read resource <resource>
• Failed to read resource <resource>

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/800a870bf5cba0e5. Report an issue: GitHub.