{"record":{"id":"f569c2c34887f882","repo":"mybatis/mybatis-3","slug":"unknown-column-is-detected-on-mappedstatement","errorCode":null,"errorMessage":"Unknown column is detected on '\" + mappedStatement.getId() + \"' auto-mapping. Mapping parameters are [columnName=\" + columnName + \",propertyName=\" + property + \",propertyType=\" + (propertyType != null ? propertyType.getTypeName() : null) + \"]","messagePattern":"Unknown column is detected on '\" \\+ mappedStatement\\.getId\\(\\) \\+ \"' auto-mapping\\. Mapping parameters are \\[columnName=\" \\+ columnName \\+ \",propertyName=\" \\+ property \\+ \",propertyType=\" \\+ \\(propertyType != null \\? propertyType\\.getTypeName\\(\\) : null\\) \\+ \"\\]","errorType":"exception","errorClass":"SqlSessionException","httpStatus":null,"severity":"error","filePath":"src/main/java/org/apache/ibatis/session/AutoMappingUnknownColumnBehavior.java","lineNumber":60,"sourceCode":"\n  /**\n   * Output warning log. Note: The log level of {@code 'org.apache.ibatis.session.AutoMappingUnknownColumnBehavior'}\n   * must be set to {@code WARN}.\n   */\n  WARNING {\n    @Override\n    public void doAction(MappedStatement mappedStatement, String columnName, String property, Type propertyType) {\n      LogHolder.log.warn(buildMessage(mappedStatement, columnName, property, propertyType));\n    }\n  },\n\n  /**\n   * Fail mapping. Note: throw {@link SqlSessionException}.\n   */\n  FAILING {\n    @Override\n    public void doAction(MappedStatement mappedStatement, String columnName, String property, Type propertyType) {\n      throw new SqlSessionException(buildMessage(mappedStatement, columnName, property, propertyType));\n    }\n  };\n\n  /**\n   * Perform the action when detects an unknown column (or unknown property type) of automatic mapping target.\n   *\n   * @param mappedStatement\n   *          current mapped statement\n   * @param columnName\n   *          column name for mapping target\n   * @param propertyName\n   *          property name for mapping target\n   * @param propertyType\n   *          property type for mapping target (If this argument is not null, {@link org.apache.ibatis.type.TypeHandler}\n   *          for property type is not registered)\n   */\n  public abstract void doAction(MappedStatement mappedStatement, String columnName, String propertyName,\n      Type propertyType);","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/mybatis/mybatis-3/blob/008069adb1b089579b5dcba87ee591908b263274/src/main/java/org/apache/ibatis/session/AutoMappingUnknownColumnBehavior.java#L42-L78","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","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.","Verify mapUnderscoreToCamelCase setting matches your column naming convention."],"exampleFix":"// before\nSELECT usr_name, extra_col FROM users  <!-- resultType User has no extraCol, no usrName match -->\n// after\nSELECT usr_name AS userName FROM users  <!-- and User has userName; or add the field -->","handlingStrategy":"validation","validationCode":"// During development/tests, enumerate expected columns vs result type fields\nSet<String> props = reflectionUtils.propertyNames(User.class); // implement once\nResultSetMetaData md = rs.getMetaData();\nfor (int i = 1; i <= md.getColumnCount(); i++) {\n  if (!props.contains(camel(md.getColumnName(i)))) throw new IllegalStateException(\"unmapped column \" + md.getColumnName(i));\n}","typeGuard":null,"tryCatchPattern":"try { session.selectList(\"findUsers\"); }\ncatch (SqlSessionException e) { /* message names column + property; add field or explicit resultMap */ throw e; }","preventionTips":["Run integration tests with autoMappingUnknownColumnBehavior=FAILING to catch mapping drift early.","Prefer explicit <resultMap> for stable contracts; rely on auto-mapping only for simple, co-owned POJOs.","Set mapUnderscoreToCamelCase consistently with your column naming."],"tags":["mybatis","auto-mapping","result-mapping","configuration"],"backgroundTag":null,"analyzedSha":"008069adb1b089579b5dcba87ee591908b263274","analyzedAt":"2026-08-14T13:07:10.264Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}