mybatis/mybatis-3 · error · BuilderException

The setting {key} is not known. Make sure you spelled it co

Error message

The setting {key} is not known.  Make sure you spelled it correctly (case sensitive).

What it means

Error "The setting {key} is not known. Make sure you spelled it correctly (case sensitive)." thrown in mybatis/mybatis-3.

Source

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

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

  private void loadCustomVfsImpl(Properties props) throws ClassNotFoundException {
    String value = props.getProperty("vfsImpl");
    if (value == null) {
      return;
    }
    String[] clazzes = value.split(",");
    for (String clazz : clazzes) {
      if (!clazz.isEmpty()) {
        @SuppressWarnings("unchecked")
        Class<? extends VFS> vfsImpl = (Class<? extends VFS>) Resources.classForName(clazz);
        configuration.setVfsImpl(vfsImpl);
      }

View on GitHub (pinned to 008069adb1)

Solutions

1. Correct the setting name in mybatis-config.xml; setting names are case sensitive.
2. Compare the key against the list of supported settings in the MyBatis configuration documentation.
3. Remove the setting if it is obsolete or belongs to a different MyBatis version.

When it happens

Trigger: Thrown at src/main/java/org/apache/ibatis/builder/xml/XMLConfigBuilder.java:146 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/d9c6ae3d8f4d6241. Report an issue: GitHub.