flowable/flowable-engine · error · FlowableException

Failed to load type handler class

Error message

Failed to load type handler class

What it means

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.

Source

Thrown at modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/AbstractEngineConfigurator.java:139

                                throw new FlowableException("Failed to load type alias class", e);
                            }
                        }
                    };
                    typeAliasConfigurators.add(typeAlias);
                    
                }
                
                NodeList typeHandlerList = document.getElementsByTagName("tagHandler");
                for (int i = 0; i < typeHandlerList.getLength(); i++) {
                    Node node = typeHandlerList.item(i);
                    MybatisTypeHandlerConfigurator typeHandler = new MybatisTypeHandlerConfigurator() {
                        @Override
                        public void configure(AbstractEngineConfiguration abstractEngineConfiguration, TypeHandlerRegistry typeHandlerRegistry) {
                            try {
                                typeHandlerRegistry.register(node.getAttributes().getNamedItem("javaType").getTextContent(),
                                                node.getAttributes().getNamedItem("handler").getTextContent());
                            } catch (Exception e) {
                                throw new FlowableException("Failed to load type handler class", e);
                            }
                        }
                    };
                    typeHandlerConfigurators.add(typeHandler);
                }
                
                NodeList nodeList = document.getElementsByTagName("mapper");
                for (int i = 0; i < nodeList.getLength(); i++) {
                    Node node = nodeList.item(i);
                    resources.add(node.getAttributes().getNamedItem("resource").getTextContent());
                }
                
            } catch (IOException e) {
                throw new FlowableException("Could not read IDM Mybatis configuration file", e);
            } catch (ParserConfigurationException | SAXException e) {
                throw new FlowableException("Could not parse Mybatis configuration file", e);
            }
            

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Check the cause for ClassNotFoundException/ClassCastException and fix the 'handler' attribute
2. Verify the type handler class exists on the runtime classpath and implements MyBatis' TypeHandler
3. Ensure javaType names a resolvable class in the same environment

Example fix

// before
<typeHandler javaType="com.example.Custom" handler="com.example.MissingHandler"/>
// after
<typeHandler javaType="com.example.Custom" handler="com.example.CustomTypeHandler"/>

try { Class.forName("com.example.CustomTypeHandler"); } catch (ClassNotFoundException e) { throw new IllegalStateException("typeHandler class not on classpath", e); }

try { engine = cfg.buildProcessEngine(); } catch (FlowableException e) { if ("Failed to load type handler class".equals(e.getMessage())) { /* inspect e.getCause() */ } throw e; }

When it happens

Trigger: registerCustomMybatisMappings (invoked from beforeInit) processing a <typeHandler> node whose javaType/handler attributes point to classes that cannot be resolved or fail registration.

Common situations: Custom type handler class missing from classpath, typo in the handler class name, handler not implementing TypeHandler, classpath isolation in app servers.

Related errors

• Failed to load type alias class
• Could not read IDM Mybatis configuration file
• Class ${customMybatisMapperClassName} has not been found.
• resource '${resource}' not found
• Failed to read resource ${resource}

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