flowable/flowable-engine · error · FlowableException

Failed to load type alias class

Error message

Failed to load type alias class

What it means

When registering custom MyBatis mappings from a dependent-engine XML config, <typeAlias> entries are resolved by loading the class named in the 'type' attribute via Class.forName and registering it under 'alias'. If the alias registration fails (class not on classpath, invalid name), this FlowableException is thrown.

Source

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

            List<MybatisTypeAliasConfigurator> typeAliasConfigurators = new ArrayList<>();
            List<MybatisTypeHandlerConfigurator> typeHandlerConfigurators = new ArrayList<>();
            try (InputStream inputStream = classLoader.getResourceAsStream(cfgPath)) {
                DocumentBuilderFactory docBuilderFactory = createDocumentBuilderFactory();
                DocumentBuilder docBuilder = docBuilderFactory.newDocumentBuilder();
                Document document = docBuilder.parse(inputStream);
                
                NodeList typeAliasList = document.getElementsByTagName("typeAlias");
                for (int i = 0; i < typeAliasList.getLength(); i++) {
                    Node node = typeAliasList.item(i);
                    MybatisTypeAliasConfigurator typeAlias = new MybatisTypeAliasConfigurator() {
                        @Override
                        public void configure(AbstractEngineConfiguration abstractEngineConfiguration, TypeAliasRegistry typeAliasRegistry) {
                            try {
                                typeAliasRegistry.registerAlias(node.getAttributes().getNamedItem("alias").getTextContent(), 
                                                Class.forName(node.getAttributes().getNamedItem("type").getTextContent()));
                            } catch (Exception e) {
                                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);

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Check the cause: likely ClassNotFoundException — confirm the class is on the runtime classpath
2. Fix the 'type' attribute in the custom MyBatis XML to the correct fully-qualified class name
3. Ensure the jar containing the alias class is deployed in the same classloader as the engine

Example fix

// before
<typeAlias alias="myVar" type="com.example.MyVariable"/> <!-- class missing -->
// after
<typeAlias alias="myVar" type="com.example.variables.MyVariable"/> <!-- correct FQN on classpath -->

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

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

When it happens

Trigger: registerCustomMybatisMappings (invoked from beforeInit) processing a <typeAlias> node whose 'type' attribute names a class that cannot be loaded or an alias that cannot be registered.

Common situations: Custom alias class not packaged/deployed with the app, typo in fully-qualified class name, class present in a different classloader (e.g. app server module), renaming/moving the class after upgrade.

Related errors

• Failed to load type handler 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/3d74b6c96ed46764. Report an issue: GitHub.