flowable/flowable-engine · error · FlowableException

Could not parse Mybatis configuration file

Error message

Could not parse Mybatis configuration file

What it means

registerCustomMybatisMappings parses the custom MyBatis XML configuration with a DOM parser. If the document is malformed XML (ParserConfigurationException or SAXException), the engine throws this FlowableException with the parse error as cause.

Source

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

                                                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);
            }
            
            if (typeAliasConfigurators.size() > 0) {
                if (engineConfiguration.getDependentEngineMybatisTypeAliasConfigs() == null) {
                    engineConfiguration.setDependentEngineMybatisTypeAliasConfigs(typeAliasConfigurators);
                    
                } else {
                    engineConfiguration.getDependentEngineMybatisTypeAliasConfigs().addAll(typeAliasConfigurators);
                }
            }
            
            if (typeHandlerConfigurators.size() > 0) {
                if (engineConfiguration.getDependentEngineMybatisTypeHandlerConfigs() == null) {
                    engineConfiguration.setDependentEngineMybatisTypeHandlerConfigs(typeHandlerConfigurators);
                    
                } else {
                    engineConfiguration.getDependentEngineMybatisTypeHandlerConfigs().addAll(typeHandlerConfigurators);
                }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Validate the XML file with an XML parser/linter and fix syntax errors
2. Check the wrapped cause (SAXParseException) for the exact line/column of the problem
3. Replace the file with a known-good copy and re-deploy

try { DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(new File("mybatis-mappings.xml")); } catch (SAXException | ParserConfigurationException | IOException e) { throw new IllegalStateException("invalid MyBatis XML", e); }

try { engine = cfg.buildProcessEngine(); } catch (FlowableException e) { if (e.getMessage().contains("Could not parse")) { log.error("XML parse error", e.getCause()); } throw e; }

When it happens

Trigger: beforeInit -> registerCustomMybatisMappings: DocumentBuilder fails to parse the custom MyBatis XML due to invalid syntax, unclosed tags, bad encoding, or invalid DTD/schema references.

Common situations: Hand-edited custom MyBatis XML with syntax errors, wrong file encoding, truncated/corrupted file in deployment, XML that doesn't follow the expected mapping-config structure.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• The bpmn 2.0 xml is not properly encoded
• Error while building ibatis SqlSessionFactory:
• Failed to load type alias class
• Failed to load type handler class
• Could not read IDM Mybatis configuration file

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