{"record":{"id":"68bf90f357634354","repo":"mybatis/mybatis-3","slug":"an-invalid-property-name-was-found-in-mapping","errorCode":null,"errorMessage":"An invalid property '{name}' was found in mapping #{{content}}.  Valid properties are {PARAMETER_PROPERTIES}","messagePattern":"An invalid property '(.+?)' was found in mapping #(.+?)\\}\\.  Valid properties are (.+?)","errorType":"exception","errorClass":"BuilderException","httpStatus":null,"severity":"error","filePath":"src/main/java/org/apache/ibatis/builder/ParameterMappingTokenHandler.java","lineNumber":121,"sourceCode":"    builder.typeHandler(typeHandler);\n\n    ParameterMode mode = null;\n    for (Map.Entry<String, String> entry : propertiesMap.entrySet()) {\n      String name = entry.getKey();\n      String value = entry.getValue();\n      if (\"mode\".equals(name)) {\n        mode = resolveParameterMode(value);\n        builder.mode(mode);\n      } else if (\"numericScale\".equals(name)) {\n        builder.numericScale(Integer.valueOf(value));\n      } else if (\"resultMap\".equals(name)) {\n        builder.resultMapId(value);\n      } else if (\"jdbcTypeName\".equals(name)) {\n        builder.jdbcTypeName(value);\n      } else if (\"expression\".equals(name)) {\n        throw new BuilderException(\"Expression based parameters are not supported yet\");\n      } else {\n        throw new BuilderException(\"An invalid property '\" + name + \"' was found in mapping #{\" + content\n            + \"}.  Valid properties are \" + PARAMETER_PROPERTIES);\n      }\n    }\n    if (!ParameterMode.OUT.equals(mode) && paramExists) {\n      if (metaParameters.hasGetter(propertyTokenizer.getName())) {\n        builder.value(metaParameters.getValue(property));\n      } else if (parameterObject == null) {\n        builder.value(null);\n      } else if (typeHandlerRegistry.hasTypeHandler(parameterObject.getClass())) {\n        builder.value(parameterObject);\n      } else {\n        MetaObject metaObject = configuration.newMetaObject(parameterObject);\n        builder.value(metaObject.getValue(property));\n      }\n    }\n    return builder.build();\n  }\n","sourceCodeStart":103,"sourceCodeEnd":139,"githubUrl":"https://github.com/mybatis/mybatis-3/blob/008069adb1b089579b5dcba87ee591908b263274/src/main/java/org/apache/ibatis/builder/ParameterMappingTokenHandler.java#L103-L139","documentation":"Thrown when a #{} placeholder option list contains a property name outside the allowed set. The valid set (PARAMETER_PROPERTIES) is javaType, jdbcType, mode, numericScale, resultMap, typeHandler, jdbcTypeName (per ParameterMapping). Unrecognized names (e.g. 'type', 'value', 'nullable') are rejected with this message listing the valid names.","triggerScenarios":"Writing #{id,type=INTEGER} instead of #{id,jdbcType=INTEGER}, or #{id,nullable=true} — any option key not in ParameterMapping's PARAMETER_PROPERTIES constant.","commonSituations":"Guessing option names ('type' instead of 'jdbcType'), copy-paste from JPA/NamedParameterJdbcTemplate style syntax, or typos like 'jdbcTyp'.","solutions":["Use one of the valid option names: javaType, jdbcType, mode, numericScale, resultType? (resultMap for OUT params), typeHandler","Check the exact spelling in the error message's PARAMETER_PROPERTIES list it prints","Remove options that are not needed — plain #{property} is usually correct"],"exampleFix":"<!-- before -->\n#{id,type=INTEGER}\n<!-- after -->\n#{id,jdbcType=INTEGER}","handlingStrategy":"validation","validationCode":"private static final Set<String> VALID = Set.of(\"javaType\",\"jdbcType\",\"mode\",\"numericScale\",\"resultMap\",\"typeHandler\");\n\nvoid checkPlaceholderOptions(String content) {\n  Map<String,String> opts = new ParameterExpression(content);\n  for (String k : opts.keySet()) {\n    if (!VALID.contains(k)) throw new IllegalArgumentException(\"Invalid #{} option '\" + k + \"' in \" + content);\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  new ParameterExpression(content);\n} catch (BuilderException e) {\n  if (e.getMessage().contains(\"Valid properties are\")) {\n    // surface allowed list to the developer\n    throw new IllegalArgumentException(\"Bad placeholder options: \" + content, e);\n  }\n  throw e;\n}","preventionTips":["Learn the valid option list once: javaType, jdbcType, mode, numericScale, resultMap, typeHandler","Let the IDE's MyBatis plugin validate mapper syntax before runtime"],"tags":["mybatis","parameter-mapping","syntax","xml-mapper"],"backgroundTag":null,"analyzedSha":"008069adb1b089579b5dcba87ee591908b263274","analyzedAt":"2026-08-14T13:07:10.264Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}