mybatis/mybatis-3 · error · BuilderException

Error parsing SQL Mapper Configuration. Cause: {cause}

Error message

Error parsing SQL Mapper Configuration. Cause: {cause}

What it means

Error "Error parsing SQL Mapper Configuration. Cause: {cause}" thrown in mybatis/mybatis-3.

Source

Thrown at src/main/java/org/apache/ibatis/builder/xml/XMLConfigBuilder.java:133

    try {
      // issue #117 read properties first
      propertiesElement(root.evalNode("properties"));
      Properties settings = settingsAsProperties(root.evalNode("settings"));
      loadCustomVfsImpl(settings);
      loadCustomLogImpl(settings);
      typeAliasesElement(root.evalNode("typeAliases"));
      pluginsElement(root.evalNode("plugins"));
      objectFactoryElement(root.evalNode("objectFactory"));
      objectWrapperFactoryElement(root.evalNode("objectWrapperFactory"));
      reflectorFactoryElement(root.evalNode("reflectorFactory"));
      settingsElement(settings);
      // read it after objectFactory and objectWrapperFactory issue #631
      environmentsElement(root.evalNode("environments"));
      databaseIdProviderElement(root.evalNode("databaseIdProvider"));
      typeHandlersElement(root.evalNode("typeHandlers"));
      mappersElement(root.evalNode("mappers"));
    } catch (Exception e) {
      throw new BuilderException("Error parsing SQL Mapper Configuration. Cause: " + e, e);
    }
  }

  private Properties settingsAsProperties(XNode context) {
    if (context == null) {
      return new Properties();
    }
    Properties props = context.getChildrenAsProperties();
    // Check that all settings are known to the configuration class
    MetaClass metaConfig = MetaClass.forClass(Configuration.class, localReflectorFactory);
    for (Object key : props.keySet()) {
      if (!metaConfig.hasSetter(String.valueOf(key))) {
        throw new BuilderException(
            "The setting " + key + " is not known.  Make sure you spelled it correctly (case sensitive).");
      }
    }
    return props;
  }

View on GitHub (pinned to 008069adb1)

Solutions

1. Check the nested cause for the specific XML problem (malformed XML, unknown element, invalid attribute).
2. Validate mybatis-config.xml against the MyBatis DTD or schema.
3. Ensure referenced resources, mapper files, and classes exist and are on the classpath.

When it happens

Trigger: Thrown at src/main/java/org/apache/ibatis/builder/xml/XMLConfigBuilder.java:133 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of mybatis/mybatis-3@008069adb1 (2026-08-14). Data as JSON: /api/errors/39c7b9ab23284b1f. Report an issue: GitHub.