{"record":{"id":"800a870bf5cba0e5","repo":"flowable/flowable-engine","slug":"failed-to-read-mapper-from","errorCode":null,"errorMessage":"Failed to read mapper from ","messagePattern":"Failed to read mapper from ","errorType":"exception","errorClass":"UncheckedIOException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/aot/FlowableMyBatisResourceHintsRegistrar.java","lineNumber":98,"sourceCode":"                        reflectionHints.registerType(Map.class, memberCategories);\n                    }\n                }\n\n                String resultType = statement.getStringAttribute(\"resultType\");\n                if (resultType != null) {\n                    if (resultType.equals(\"long\")) {\n                        reflectionHints.registerType(long.class, memberCategories);\n                        reflectionHints.registerType(Long.class, memberCategories);\n                    } else if (resultType.equals(\"string\")) {\n                        reflectionHints.registerType(String.class, memberCategories);\n                    } else if (resultType.equals(\"map\")) {\n                        reflectionHints.registerType(HashMap.class, memberCategories);\n                    }\n                }\n            }\n\n        } catch (IOException e) {\n            throw new UncheckedIOException(\"Failed to read mapper from \" + mapperPath, e);\n        }\n    }\n\n    protected static XPathParser createParser(InputStream stream) {\n        return new XPathParser(stream, false, null, new XMLMapperEntityResolver());\n    }\n\n}\n","sourceCodeStart":80,"sourceCodeEnd":107,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/aot/FlowableMyBatisResourceHintsRegistrar.java#L80-L107","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Confirm the mapper resource path exists: classLoader.getResource(\"org/flowable/db/mapping/entity/Job.xml\") etc., and fix the path if renamed.","Include custom and engine mapper XMLs in the artifact (Maven/Gradle resource config, Spring Boot layers).","Register mapper XMLs as native resources so the stream is available at AOT/native runtime.","Upgrade/align Flowable modules so built-in mapper paths match the engine version on the classpath."],"exampleFix":"// before\nhints.resources().registerPattern(\"org/flowable/db/mapping/*.xml\"); // misses subfolders\n// after\nhints.resources().registerPattern(\"org/flowable/db/mapping/**/*.xml\");","handlingStrategy":"validation","validationCode":"String mapperPath = mapper.getStringAttribute(\"resource\");\nif (classLoader.getResource(mapperPath) == null) throw new IllegalStateException(\"Mapper resource missing from classpath: \" + mapperPath);","typeGuard":null,"tryCatchPattern":"try {\n  registerMapper(mapperPath, hints, classLoader);\n} catch (UncheckedIOException e) {\n  if (e.getMessage().startsWith(\"Failed to read mapper from\")) {\n    log.error(\"Cannot read mapper XML: {}\", mapperPath, e);\n  }\n  throw e;\n}","preventionTips":["Package custom mapper XMLs into the jar and verify paths after engine upgrades.","Register '**/db/mapping/**/*.xml' patterns in native-image resource hints.","Confirm every mapper resource attribute resolves via classLoader.getResource().","Keep all Flowable modules version-aligned so built-in mapper paths match."],"tags":["mybatis","aot","resource","io"],"backgroundTag":"file-read-failed","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}