mybatis/mybatis-3 · error · IllegalArgumentException

name + " does not contain value for " + key

Error message

name + " does not contain value for " + key

What it means

Configuration.StrictMap.get() throws IllegalArgumentException(name + " does not contain value for " + key) when a lookup by full statement name misses. In practice this is the classic "Mapped Statements collection does not contain value for ..." path's underlying mechanism: the runtime asked Configuration for a statement (or resultMap/sql fragment) whose fully-qualified name is not registered — wrong namespace, wrong id, or the mapper was never loaded.

Source

Thrown at src/main/java/org/apache/ibatis/session/Configuration.java:1185

        }
      }
      return super.put(key, value);
    }

    @Override
    public boolean containsKey(Object key) {
      if (key == null) {
        return false;
      }

      return super.get(key) != null;
    }

    @Override
    public V get(Object key) {
      V value = super.get(key);
      if (value == null) {
        throw new IllegalArgumentException(name + " does not contain value for " + key);
      }
      if (AMBIGUITY_INSTANCE == value) {
        throw new IllegalArgumentException(key + " is ambiguous in " + name
            + " (try using the full name including the namespace, or rename one of the entries)");
      }
      return value;
    }

    private String getShortName(String key) {
      final String[] keyParts = key.split("\\.");
      return keyParts[keyParts.length - 1];
    }
  }

}

View on GitHub (pinned to 008069adb1)

Solutions

1. Verify the exact string used to look up the statement against the XML namespace + id (or the interface's fully-qualified name + method name).
2. Confirm the mapper XML is actually loaded: check <mappers> in mybatis-config.xml or Spring mapperLocations pattern (prefer classpath*:com/acce/**/*Mapper.xml).
3. Align the XML namespace attribute with the mapper interface's fully-qualified name and the statement ids with method names.
4. Add an annotated statement (@Select etc.) or an XML statement for the missing method.

Example fix

// before
sqlSession.selectOne("com.acme.userMapper.findById", 1);
// after
sqlSession.selectOne("com.acme.UserMapper.findById", 1);  // matches namespace exactly

// Centralize statement names instead of string literals
public final class Stmts { public static final String FIND_BY_ID = UserMapper.class.getName() + ".findById"; }
Configuration c = factory.getConfiguration();
if (!c.hasStatement(Stmts.FIND_BY_ID)) throw new IllegalStateException("statement not registered: " + Stmts.FIND_BY_ID);

try { session.selectOne(name, param); }
catch (IllegalArgumentException e) { /* 'does not contain value for' -> typo or mapper not loaded */ throw e; }

When it happens

Trigger: Calling sqlSession.selectOne("com.acme.UserMapper.findById", ...) when the namespace is misspelled or the mapper XML is not registered; invoking a mapper interface method whose XML file is not in mapperLocations; namespace attribute not matching the interface's package-qualified name; interface bound via annotation but method has no @Select and no XML statement.

Common situations: Spring Boot mybatis.mapper-locations pattern missing a folder (classpath*: vs classpath:); renaming a package without updating XML namespaces; forgetting to add the <mapper> entry in mybatis-config.xml; method name in interface differs from XML statement id.

Related errors

• Invalid bound statement (not found): {mapperInterface}.{meth
• key + " is ambiguous in " + name + " (try using the full nam
• Type {type} is not known to the MapperRegistry.
• Error resolving JdbcType. Cause: {cause}
• Error resolving ResultSetType. Cause: {cause}

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