baomidou/mybatis-plus · error · BuilderException

The setting %s is not known. Make sure you spelled it corre

Error message

The setting %s is not known.  Make sure you spelled it correctly (case sensitive).

What it means

Thrown by settingsAsProperties when a <settings> entry in mybatis-config.xml does not correspond to a writable setter on the Configuration class. Each <setting name="..."> is validated reflectively via MetaClass.hasSetter against org.apache.ibatis.session.Configuration, and unknown names are rejected with a case-sensitive check.

Source

Thrown at mybatis-plus-core/src/main/java/com/baomidou/mybatisplus/core/MybatisXMLConfigBuilder.java:147

            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 bf67d90747)

Solutions

1. Correct the name and casing to exactly match a Configuration setter property (e.g. mapUnderscoreToCamelCase, cacheEnabled, lazyLoadingEnabled).
2. Remove any MyBatis-Plus-specific settings from the MyBatis <settings> block and set them via mybatis-plus.configuration.* in Spring Boot instead.
3. Verify the setting exists in the MyBatis version actually resolved by the dependency tree (mvn dependency:tree).

Example fix

<!-- before -->
<settings>
  <setting name="LazyLoadingEnabled" value="true"/>
  <setting name="mybatis-plus.cache" value="true"/>
</settings>

<!-- after -->
<settings>
  <setting name="lazyLoadingEnabled" value="true"/>
</settings>

// check setting names against Configuration setters before building
org.apache.ibatis.reflection.MetaClass mc = org.apache.ibatis.reflection.MetaClass
    .forClass(org.apache.ibatis.session.Configuration.class, new org.apache.ibatis.reflection.DefaultReflectorFactory());
for (String name : Arrays.asList("mapUnderscoreToCamelCase", "lazyLoadingEnabled")) {
    if (!mc.hasSetter(name)) throw new IllegalStateException("Unknown setting: " + name);
}

Catch BuilderException 'The setting ... is not known' during startup; correct or remove the named setting (given verbatim in the message) and restart.

When it happens

Trigger: Including <setting name="cacheEnabled " .../> (trailing space), a misspelled name like "lazyLoadingEnabeld", or a MyBatis-Plus-specific property incorrectly placed in the MyBatis <settings> block instead of the Spring property namespace.

Common situations: Typos or wrong casing in setting names; copying setting names from mybatis-plus documentation into the mybatis <settings> element; names valid only in newer/older MyBatis versions than the one on the classpath.

Related errors

• Each XMLConfigBuilder can only be used once.
• Error parsing SQL Mapper Configuration. Cause: %s
• The properties element cannot specify both a URL and a resou
• Environment declaration requires a TransactionFactory.
• Environment declaration requires a DataSourceFactory.

AI-assisted analysis of baomidou/mybatis-plus@bf67d90747 (2026-08-14). Data as JSON: /api/errors/32f8bb157651b332. Report an issue: GitHub.