mybatis/mybatis-3 · error · IncompleteElementException

Could not find parameter map {parameterMapName}

Error message

Could not find parameter map {parameterMapName}

What it means

Thrown by getStatementParameterMap() when configuration.getParameterMap() raises IllegalArgumentException: a statement references a <parameterMap> id that is not registered. It is an IncompleteElementException so the statement is retried later; it is fatal if the parameter map never appears. Note parameterMap is a legacy construct predating #{} inline parameters.

Source

Thrown at src/main/java/org/apache/ibatis/builder/MapperBuilderAssistant.java:307

      LanguageDriver lang) {
    return addMappedStatement(id, sqlSource, statementType, sqlCommandType, fetchSize, timeout, parameterMap,
        parameterType, resultMap, resultType, resultSetType, flushCache, useCache, resultOrdered, keyGenerator,
        keyProperty, keyColumn, databaseId, lang, null);
  }

  private <T> T valueOrDefault(T value, T defaultValue) {
    return value == null ? defaultValue : value;
  }

  private ParameterMap getStatementParameterMap(String parameterMapName, Class<?> parameterTypeClass,
      String statementId) {
    parameterMapName = applyCurrentNamespace(parameterMapName, true);
    ParameterMap parameterMap = null;
    if (parameterMapName != null) {
      try {
        parameterMap = configuration.getParameterMap(parameterMapName);
      } catch (IllegalArgumentException e) {
        throw new IncompleteElementException("Could not find parameter map " + parameterMapName, e);
      }
    } else if (parameterTypeClass != null) {
      parameterMap = ParameterMap.buildEmpty(statementId + "-Inline", parameterTypeClass);
    }
    return parameterMap;
  }

  private List<ResultMap> getStatementResultMaps(String resultMap, Class<?> resultType, String statementId) {
    resultMap = applyCurrentNamespace(resultMap, true);

    List<ResultMap> resultMaps = new ArrayList<>();
    if (resultMap != null) {
      String[] resultMapNames = resultMap.split(",");
      for (String resultMapName : resultMapNames) {
        try {
          resultMaps.add(configuration.getResultMap(resultMapName.trim()));
        } catch (IllegalArgumentException e) {
          throw new IncompleteElementException(

View on GitHub (pinned to 008069adb1)

Solutions

1. Prefer migrating the statement to inline #{} parameters and delete the parameterMap attribute — parameterMap is deprecated
2. Otherwise define the missing <parameterMap id="..."> element with matching parameter mappings
3. Verify the id spelling and that the defining mapper is registered/loaded

Example fix

<!-- before -->
<select id="find" parameterMap="userParams">
  <parameterMap id="userParams">...</parameterMap>
<!-- after -->
<select id="find" parameterType="User">
  SELECT * FROM users WHERE id = #{id}
</select>

// Fail fast on legacy parameterMap usage: reject it at lint time
NodeList pm = mapperXml.getElementsByTagName("parameterMap");
NodeList refs = mapperXml.getElementsByTagName("select");
if (pm.getLength() > 0) {
  throw new IllegalStateException("parameterMap is deprecated — migrate '" + resource + "' to #{} inline parameters");
}

When it happens

Trigger: <select parameterMap="someMap"> where no <parameterMap id="someMap"> exists (or exists in a mapper not yet parsed / not registered).

Common situations: Very old tutorials or legacy codebases using parameterMap; typo in the id; mapper containing the parameterMap not scanned by Spring's mapperLocations; migration from parameterMap to #{} leaving dangling references.

Related errors

• No cache for namespace '{namespace}' could be found.
• Could not find a parent resultMap with id '{extend}'
• Cache-ref not yet resolved
• Could not find result map '{resultMapName}' referenced from
• Unknown execution method for: {name}

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