{"record":{"id":"b981f5b66aa7dc72","repo":"flowable/flowable-engine","slug":"class-custommybatismapperclassname-has-not-been","errorCode":null,"errorMessage":"Class ${customMybatisMapperClassName} has not been found.","messagePattern":"Class (.+?) has not been found\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"critical","filePath":"modules/flowable-spring-boot/flowable-spring-boot-starters/flowable-spring-boot-autoconfigure/src/main/java/org/flowable/spring/boot/AbstractEngineAutoConfiguration.java","lineNumber":121,"sourceCode":"            }\n\n            if (result.isEmpty()) {\n                logger.info(\"No deployment resources were found for autodeployment\");\n            }\n\n            return result;\n        }\n        return new ArrayList<>();\n    }\n\n    protected Set<Class<?>> getCustomMybatisMapperClasses(List<String> customMyBatisMappers) {\n        Set<Class<?>> mybatisMappers = new HashSet<>();\n        for (String customMybatisMapperClassName : customMyBatisMappers) {\n            try {\n                Class customMybatisClass = Class.forName(customMybatisMapperClassName);\n                mybatisMappers.add(customMybatisClass);\n            } catch (ClassNotFoundException e) {\n                throw new IllegalArgumentException(\"Class \" + customMybatisMapperClassName + \" has not been found.\", e);\n            }\n        }\n        return mybatisMappers;\n    }\n\n    protected String defaultText(String deploymentName, String defaultName) {\n        if (StringUtils.hasText(deploymentName)) {\n            return deploymentName;\n        }\n        return defaultName;\n    }\n\n}\n","sourceCodeStart":103,"sourceCodeEnd":135,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-spring-boot/flowable-spring-boot-starters/flowable-spring-boot-autoconfigure/src/main/java/org/flowable/spring/boot/AbstractEngineAutoConfiguration.java#L103-L135","documentation":"During Flowable engine auto-configuration (Spring Boot), getCustomMybatisMapperClasses loads each class named in the customMyBatisMappers property via Class.forName and throws IllegalArgumentException when the class cannot be found on the classpath. MyBatis mapper interfaces must be present as classes for the engine to register them, so a misspelled or missing mapper class aborts engine startup. The ClassNotFoundException is chained as the cause.","triggerScenarios":"Spring Boot app startup with flowable.*.custom-mybatis-mappers containing a class name that is not on the application classpath (typo, wrong package, missing dependency, renamed class, missing module jar).","commonSituations":"Fully-qualified name typo in application.yml/properties; custom mapper interface defined in a module not included in the deployment; class renamed after a refactor or Flowable version upgrade; configuring mappers for an engine (e.g. cmmn) whose module isn't on the classpath.","solutions":["Correct the fully-qualified class name in the custom-mybatis-mappers property (check spelling/package).","Add the jar/module containing the mapper interface to the application classpath.","Verify the class exists with Class.forName or an IDE 'go to class' before configuring it.","If the mapper became unnecessary after an upgrade, remove its entry from the property."],"exampleFix":"// before (application.yml)\nflowable:\n  custom-mybatis-mappers: com.example.mappers.TaskExstensionMapper\n\n// after (typo fixed)\nflowable:\n  custom-mybatis-mappers: com.example.mappers.TaskExtensionMapper","handlingStrategy":"validation","validationCode":"// Fail fast at startup, before Spring context builds the engine\nfor (String name : props.getCustomMybatisMappers()) {\n  try {\n    Class.forName(name);\n  } catch (ClassNotFoundException e) {\n    throw new IllegalStateException(\"Mapper class not on classpath: \" + name, e);\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Copy fully-qualified mapper names from the IDE (FQN) rather than typing them.","Ensure the module/jar containing the mapper interface is a runtime dependency.","After refactors or Flowable upgrades, re-run startup smoke tests that build the engine.","Keep custom mapper classes in a stable package to avoid rename breakage."],"tags":["spring-boot","flowable","mybatis","classpath","startup"],"backgroundTag":"class-not-found","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"}