mybatis/mybatis-3 · error · ExecutorException

If SelectKey has key columns, the number must match the numb

Error message

If SelectKey has key columns, the number must match the number of key properties.

What it means

When a <selectKey> declares both keyProperty (possibly multiple) and keyColumn, handleMultipleProperties pairs them by index. If the number of key columns does not equal the number of key properties, the pairing is ambiguous, so MyBatis throws this ExecutorException before assigning anything.

Source

Thrown at src/main/java/org/apache/ibatis/executor/keygen/SelectKeyGenerator.java:105

      }
    } catch (ExecutorException e) {
      throw e;
    } catch (Exception e) {
      throw new ExecutorException("Error selecting key or setting result to parameter object. Cause: " + e, e);
    }
  }

  private void handleMultipleProperties(String[] keyProperties, MetaObject metaParam, MetaObject metaResult) {
    String[] keyColumns = keyStatement.getKeyColumns();

    if (keyColumns == null || keyColumns.length == 0) {
      // no key columns specified, just use the property names
      for (String keyProperty : keyProperties) {
        setValue(metaParam, keyProperty, metaResult.getValue(keyProperty));
      }
    } else {
      if (keyColumns.length != keyProperties.length) {
        throw new ExecutorException(
            "If SelectKey has key columns, the number must match the number of key properties.");
      }
      for (int i = 0; i < keyProperties.length; i++) {
        setValue(metaParam, keyProperties[i], metaResult.getValue(keyColumns[i]));
      }
    }
  }

  private void setValue(MetaObject metaParam, String property, Object value) {
    if (!metaParam.hasSetter(property)) {
      throw new ExecutorException("No setter found for the keyProperty '" + property + "' in "
          + metaParam.getOriginalObject().getClass().getName() + ".");
    }
    metaParam.setValue(property, value);
  }
}

View on GitHub (pinned to 008069adb1)

Solutions

1. Count entries: keyColumn must have exactly as many comma-separated names as keyProperty
2. Order both lists identically since pairing is positional
3. If the select returns a single value, drop keyColumn entirely and keep one keyProperty

Example fix

<!-- before -->
<selectKey keyProperty="id,name" keyColumn="id" ...>

<!-- after -->
<selectKey keyProperty="id,name" keyColumn="id,name" ...>

// Startup config lint: keyColumn count must equal keyProperty count
if (keyColumns != null && keyColumns.length != keyProperties.length) {
  throw new IllegalStateException("<selectKey> keyProperty/keyColumn count mismatch");
}

When it happens

Trigger: keyProperty="id,name" with keyColumn="id" (or vice versa); composite-key selects where columns and properties are listed with different lengths; stray comma or missing entry in one of the two attributes.

Common situations: Adding a second key property and forgetting to add its column, or renaming and dropping one side only.

Related errors

• Invalid bound statement (not found): {mapperInterface}.{meth
• Type {type} is not known to the MapperRegistry.
• Error resolving JdbcType. Cause: {cause}
• Error resolving ResultSetType. Cause: {cause}
• Error creating instance. Cause: {cause}

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