{"record":{"id":"5ffb5bd52e33c652","repo":"flowable/flowable-engine","slug":"failed-to-load-type-handler-class","errorCode":null,"errorMessage":"Failed to load type handler class","messagePattern":"Failed to load type handler class","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/AbstractEngineConfigurator.java","lineNumber":139,"sourceCode":"                                throw new FlowableException(\"Failed to load type alias class\", e);\n                            }\n                        }\n                    };\n                    typeAliasConfigurators.add(typeAlias);\n                    \n                }\n                \n                NodeList typeHandlerList = document.getElementsByTagName(\"tagHandler\");\n                for (int i = 0; i < typeHandlerList.getLength(); i++) {\n                    Node node = typeHandlerList.item(i);\n                    MybatisTypeHandlerConfigurator typeHandler = new MybatisTypeHandlerConfigurator() {\n                        @Override\n                        public void configure(AbstractEngineConfiguration abstractEngineConfiguration, TypeHandlerRegistry typeHandlerRegistry) {\n                            try {\n                                typeHandlerRegistry.register(node.getAttributes().getNamedItem(\"javaType\").getTextContent(),\n                                                node.getAttributes().getNamedItem(\"handler\").getTextContent());\n                            } catch (Exception e) {\n                                throw new FlowableException(\"Failed to load type handler class\", e);\n                            }\n                        }\n                    };\n                    typeHandlerConfigurators.add(typeHandler);\n                }\n                \n                NodeList nodeList = document.getElementsByTagName(\"mapper\");\n                for (int i = 0; i < nodeList.getLength(); i++) {\n                    Node node = nodeList.item(i);\n                    resources.add(node.getAttributes().getNamedItem(\"resource\").getTextContent());\n                }\n                \n            } catch (IOException e) {\n                throw new FlowableException(\"Could not read IDM Mybatis configuration file\", e);\n            } catch (ParserConfigurationException | SAXException e) {\n                throw new FlowableException(\"Could not parse Mybatis configuration file\", e);\n            }\n            ","sourceCodeStart":121,"sourceCodeEnd":157,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/AbstractEngineConfigurator.java#L121-L157","documentation":"When registering custom MyBatis mappings from a dependent-engine XML config, <typeHandler> entries are registered against the TypeHandlerRegistry using 'javaType' and 'handler' attributes. If registration fails (handler class unresolvable/invalid), this FlowableException is thrown.","triggerScenarios":"registerCustomMybatisMappings (invoked from beforeInit) processing a <typeHandler> node whose javaType/handler attributes point to classes that cannot be resolved or fail registration.","commonSituations":"Custom type handler class missing from classpath, typo in the handler class name, handler not implementing TypeHandler, classpath isolation in app servers.","solutions":["Check the cause for ClassNotFoundException/ClassCastException and fix the 'handler' attribute","Verify the type handler class exists on the runtime classpath and implements MyBatis' TypeHandler","Ensure javaType names a resolvable class in the same environment"],"exampleFix":"// before\n<typeHandler javaType=\"com.example.Custom\" handler=\"com.example.MissingHandler\"/>\n// after\n<typeHandler javaType=\"com.example.Custom\" handler=\"com.example.CustomTypeHandler\"/>","handlingStrategy":"validation","validationCode":"try { Class.forName(\"com.example.CustomTypeHandler\"); } catch (ClassNotFoundException e) { throw new IllegalStateException(\"typeHandler class not on classpath\", e); }","typeGuard":null,"tryCatchPattern":"try { engine = cfg.buildProcessEngine(); } catch (FlowableException e) { if (\"Failed to load type handler class\".equals(e.getMessage())) { /* inspect e.getCause() */ } throw e; }","preventionTips":["Ensure handler classes implement org.apache.ibatis.type.TypeHandler","Verify handler and javaType attributes point to real resolvable classes","Smoke-test custom MyBatis mappings at startup"],"tags":["flowable","mybatis","type-handler","classpath"],"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"}