mybatis/mybatis-3 · error · SqlSessionException

Unknown column is detected on '" + mappedStatement.getId() +

Error message

Unknown column is detected on '" + mappedStatement.getId() + "' auto-mapping. Mapping parameters are [columnName=" + columnName + ",propertyName=" + property + ",propertyType=" + (propertyType != null ? propertyType.getTypeName() : null) + "]

What it means

During result auto-mapping, when a result set column cannot be matched to any property of the result type, MyBatis consults configuration setting autoMappingUnknownColumnBehavior. With FAILING, doAction throws a SqlSessionException whose message lists the mapped statement id, the column name, the candidate property, and its type. This turns silent data loss (unmapped column) into a hard runtime error.

Source

Thrown at src/main/java/org/apache/ibatis/session/AutoMappingUnknownColumnBehavior.java:60

  /**
   * Output warning log. Note: The log level of {@code 'org.apache.ibatis.session.AutoMappingUnknownColumnBehavior'}
   * must be set to {@code WARN}.
   */
  WARNING {
    @Override
    public void doAction(MappedStatement mappedStatement, String columnName, String property, Type propertyType) {
      LogHolder.log.warn(buildMessage(mappedStatement, columnName, property, propertyType));
    }
  },

  /**
   * Fail mapping. Note: throw {@link SqlSessionException}.
   */
  FAILING {
    @Override
    public void doAction(MappedStatement mappedStatement, String columnName, String property, Type propertyType) {
      throw new SqlSessionException(buildMessage(mappedStatement, columnName, property, propertyType));
    }
  };

  /**
   * Perform the action when detects an unknown column (or unknown property type) of automatic mapping target.
   *
   * @param mappedStatement
   *          current mapped statement
   * @param columnName
   *          column name for mapping target
   * @param propertyName
   *          property name for mapping target
   * @param propertyType
   *          property type for mapping target (If this argument is not null, {@link org.apache.ibatis.type.TypeHandler}
   *          for property type is not registered)
   */
  public abstract void doAction(MappedStatement mappedStatement, String columnName, String propertyName,
      Type propertyType);

View on GitHub (pinned to 008069adb1)

Solutions

1. Add the missing property (with matching name or a supported underscore/camel mapping) to the result type, or use column aliasing so column and property names match.
2. If the column is intentionally ignored, define an explicit <resultMap> with autoMapping="false" or map only needed columns, or set behavior back to WARNING/NONE.
3. Verify mapUnderscoreToCamelCase setting matches your column naming convention.

Example fix

// before
SELECT usr_name, extra_col FROM users  <!-- resultType User has no extraCol, no usrName match -->
// after
SELECT usr_name AS userName FROM users  <!-- and User has userName; or add the field -->

// During development/tests, enumerate expected columns vs result type fields
Set<String> props = reflectionUtils.propertyNames(User.class); // implement once
ResultSetMetaData md = rs.getMetaData();
for (int i = 1; i <= md.getColumnCount(); i++) {
  if (!props.contains(camel(md.getColumnName(i)))) throw new IllegalStateException("unmapped column " + md.getColumnName(i));
}

try { session.selectList("findUsers"); }
catch (SqlSessionException e) { /* message names column + property; add field or explicit resultMap */ throw e; }

When it happens

Trigger: autoMappingUnknownColumnBehavior=FAILING in mybatis-config.xml (or Spring boot property mybatis.configuration.auto-mapping-unknown-column-behavior=failing) plus: a SELECT column with no matching resultType property; a column/property naming mismatch that fuzzy matching cannot resolve; a resultMap autoMapping override; a DB schema change adding a column.

Common situations: DBA adds a column to a view/table and old resultType POJOs lack the field; alias typo in SELECT (USR_NAME vs userName); teams enabling FAILING in tests to catch mapping drift and then hitting it in CI; case-sensitive matching on unusual column names.

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/f569c2c34887f882. Report an issue: GitHub.