flowable/flowable-engine · error · FlowableException

Could not read IDM Mybatis configuration file

Error message

Could not read IDM Mybatis configuration file

What it means

registerCustomMybatisMappings parses the dependent engine's custom MyBatis XML configuration file from the classpath. If the file cannot be read (IOException while opening/resolving the resource), the engine throws this FlowableException.

Source

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

                            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);
            }
            
            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 {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Confirm the XML resource exists on the runtime classpath at the exact path referenced
2. Check the wrapped IOException cause for the actual path resolution problem
3. Add the resource to build packaging (e.g. maven resources include) if it is being filtered out

String path = "custom/mybatis-mappings.xml"; if (getClass().getClassLoader().getResource(path) == null) { throw new IllegalStateException("MyBatis config resource missing: " + path); }

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

When it happens

Trigger: beforeInit -> registerCustomMybatisMappings: the custom MyBatis XML resource (e.g. referenced by a dependent engine configurator) cannot be opened via its resource path — resource missing from classpath, wrong path, unreadable stream.

Common situations: Custom MyBatis XML not packaged into the deployed jar/war, resource path typo, file present in source but excluded by build filters.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Failed to load type alias class
• Failed to load type handler class
• 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/553a758d56cebbbf. Report an issue: GitHub.