{"record":{"id":"03977324d37ef347","repo":"baomidou/mybatis-plus","slug":"error-parsing-sql-mapper-configuration-cause-s","errorCode":null,"errorMessage":"Error parsing SQL Mapper Configuration. Cause: %s","messagePattern":"Error parsing SQL Mapper Configuration\\. Cause: (.+?)","errorType":"exception","errorClass":"BuilderException","httpStatus":null,"severity":"error","filePath":"mybatis-plus-core/src/main/java/com/baomidou/mybatisplus/core/MybatisXMLConfigBuilder.java","lineNumber":134,"sourceCode":"        try {\n            // issue #117 read properties first\n            propertiesElement(root.evalNode(\"properties\"));\n            Properties settings = settingsAsProperties(root.evalNode(\"settings\"));\n            loadCustomVfsImpl(settings);\n            loadCustomLogImpl(settings);\n            typeAliasesElement(root.evalNode(\"typeAliases\"));\n            pluginsElement(root.evalNode(\"plugins\"));\n            objectFactoryElement(root.evalNode(\"objectFactory\"));\n            objectWrapperFactoryElement(root.evalNode(\"objectWrapperFactory\"));\n            reflectorFactoryElement(root.evalNode(\"reflectorFactory\"));\n            settingsElement(settings);\n            // read it after objectFactory and objectWrapperFactory issue #631\n            environmentsElement(root.evalNode(\"environments\"));\n            databaseIdProviderElement(root.evalNode(\"databaseIdProvider\"));\n            typeHandlersElement(root.evalNode(\"typeHandlers\"));\n            mappersElement(root.evalNode(\"mappers\"));\n        } catch (Exception e) {\n            throw new BuilderException(\"Error parsing SQL Mapper Configuration. Cause: \" + e, e);\n        }\n    }\n\n    private Properties settingsAsProperties(XNode context) {\n        if (context == null) {\n            return new Properties();\n        }\n        Properties props = context.getChildrenAsProperties();\n        // Check that all settings are known to the configuration class\n        MetaClass metaConfig = MetaClass.forClass(Configuration.class, localReflectorFactory);\n        for (Object key : props.keySet()) {\n            if (!metaConfig.hasSetter(String.valueOf(key))) {\n                throw new BuilderException(\n                    \"The setting \" + key + \" is not known.  Make sure you spelled it correctly (case sensitive).\");\n            }\n        }\n        return props;\n    }","sourceCodeStart":116,"sourceCodeEnd":152,"githubUrl":"https://github.com/baomidou/mybatis-plus/blob/bf67d907478c724120bf76292da54abf9e73c2b3/mybatis-plus-core/src/main/java/com/baomidou/mybatisplus/core/MybatisXMLConfigBuilder.java#L116-L152","documentation":"Generic wrapper thrown by parseConfiguration for any exception raised while walking the mybatis-config.xml tree (properties, settings, typeAliases, plugins, environments, typeHandlers, mappers sections). It is a facade: the specific failure is in the message ('Cause: ...') and the suppressed cause, so the real error — bad class name, malformed XML section, invalid setting — must be extracted from the cause chain.","triggerScenarios":"Any parse-time failure inside mybatis-config.xml: a <typeAlias> pointing to a missing class, an <environment> without a <transactionManager>, an interceptor class lacking a no-arg constructor, an unresolvable <properties resource=...>, or any child section throwing.","commonSituations":"Typos in fully-qualified class names inside the XML config; refactoring moving plugin classes without updating the config; environment-specific configs referencing resources absent from the classpath.","solutions":["Read the full message and stack trace to the root cause (getCause()); fix that underlying error, not this wrapper.","Validate the mybatis-config.xml element order and required children per the DTD (properties, settings, typeAliases, plugins, environments, mappers).","Check that every class referenced in the config exists at the stated package and has a public no-arg constructor.","Confirm referenced property files/resources resolve on the classpath at runtime."],"exampleFix":"<!-- before: class moved during refactor -->\n<plugins>\n  <plugin interceptor=\"com.example.oldpkg.MyPlugin\"/>\n</plugins>\n\n<!-- after -->\n<plugins>\n  <plugin interceptor=\"com.example.plugins.MyPlugin\"/>\n</plugins>","handlingStrategy":"try-catch","validationCode":"// validate XML against the MyBatis DTD before parsing\njavax.xml.XMLConstants fac = null; // placeholder\nSchemaFactory sf = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);\n// simplest practical validation: parse with DTD enabled in XMLConfigBuilder (it does by default)\n// and dry-run build at startup in a test:\nnew SqlSessionFactoryBuilder().build(Resources.getResourceAsReader(\"mybatis-config.xml\"));","typeGuard":null,"tryCatchPattern":"catch (org.apache.ibatis.builder.BuilderException e) { log.error(\"Config parse failed: {}\", e.getMessage(), e.getCause()); fail startup; } — always log the cause chain; the actionable error is e.getCause().","preventionTips":["Build the SqlSessionFactory in a unit/@SpringBootTest test so XML errors surface at build time.","Keep class references in XML synced with refactoring tools or generate them.","Run config through an XML lint with the MyBatis DTD."],"tags":["mybatis","mybatis-plus","xml-config","configuration","parse-error"],"backgroundTag":null,"analyzedSha":"bf67d907478c724120bf76292da54abf9e73c2b3","analyzedAt":"2026-08-14T15:17:09.543Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}