{"record":{"id":"7bdbc7623aed956b","repo":"hibernate/hibernate-orm","slug":"unable-to-resolve-property-propertyname","errorCode":null,"errorMessage":"Unable to resolve property: {propertyName}","messagePattern":"Unable to resolve property: (.+?)","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/persister/entity/BaseEntityPersister.java","lineNumber":760,"sourceCode":"\t\treturn identifierAssignedByInsert;\n\t}\n\n\tprotected Generator getIdentifierGenerator() {\n\t\treturn identifierGenerator;\n\t}\n\n\tpublic int getPropertySpan() {\n\t\treturn propertySpan;\n\t}\n\n\tpublic int getVersionPropertyIndex() {\n\t\treturn versionPropertyIndex;\n\t}\n\n\tpublic int getPropertyIndex(String propertyName) {\n\t\tfinal Integer index = getPropertyIndexOrNull( propertyName );\n\t\tif ( index == null ) {\n\t\t\tthrow new HibernateException( \"Unable to resolve property: \" + propertyName );\n\t\t}\n\t\treturn index;\n\t}\n\n\tpublic Integer getPropertyIndexOrNull(String propertyName) {\n\t\treturn propertyIndexes.get( propertyName );\n\t}\n\n\tpublic boolean hasCollections() {\n\t\treturn hasCollections;\n\t}\n\n\tpublic boolean hasOwnedCollections() {\n\t\treturn hasOwnedCollections;\n\t}\n\n\tpublic boolean hasMutableProperties() {\n\t\treturn !mutablePropertiesIndexes.isEmpty();","sourceCodeStart":742,"sourceCodeEnd":778,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/persister/entity/BaseEntityPersister.java#L742-L778","documentation":"BaseEntityPersister.getPropertyIndex translates a property name to its positional index via the persister's precomputed propertyIndexes map and throws HibernateException('Unable to resolve property: X') on a miss. The map holds this persister's mapped property names, so the supplied name must exactly match a mapped property — not a DB column name, and not a name registered under a different access strategy.","triggerScenarios":"Calling persister.getPropertyIndex(name) with a misspelled name, a column name, a subclass-only property against the root persister, or a name that differs due to field-vs-property access; internal callers include unique-key/natural-id resolution and snapshot handling that take property names from configuration.","commonSituations":"Renaming a field without updating reflection/config-driven callers; passing column names from external configuration; property-ref style lookups where the configured name drifted from the mapped property; annotation vs XML naming mismatches.","solutions":["Verify the name against persister.getPropertyNames() (or the JPA metamodel attributes) and fix the caller","Probe with getPropertyIndexOrNull(name) and handle null instead of calling getPropertyIndex directly","If the property lives on a subclass, resolve against the subclass persister, not the root"],"exampleFix":"// before\nint idx = persister.getPropertyIndex(\"emial\"); // typo -> HibernateException\n\n// after\nInteger idx = persister.getPropertyIndexOrNull(name);\nif ( idx == null ) {\n    throw new IllegalArgumentException(\n        \"Unknown property '\" + name + \"'; valid: \"\n        + List.of( persister.getPropertyNames() ) );\n}","handlingStrategy":"validation","validationCode":"Integer idx = persister.getPropertyIndexOrNull(propertyName);\nif ( idx == null ) {\n    throw new IllegalArgumentException(\n        \"Unknown property '\" + propertyName + \"'; valid names: \"\n        + java.util.List.of(persister.getPropertyNames()));\n}","typeGuard":null,"tryCatchPattern":"try {\n    int idx = persister.getPropertyIndex(name);\n}\ncatch ( org.hibernate.HibernateException e ) {\n    // 'Unable to resolve property: <name>' -> surface valid names to the caller\n    throw new IllegalArgumentException(\n        e.getMessage() + \"; valid: \" + java.util.List.of(persister.getPropertyNames()), e);\n}","preventionTips":["Derive property names from the JPA metamodel instead of hand-typed strings in configuration","Log persister.getPropertyNames() once at startup so mismatches are easy to diff","Remember property names, not column names, are required — and subclass properties may not resolve on the root persister"],"tags":["hibernate","orm","property-mapping","naming","mapping"],"backgroundTag":"unknown-entity-property","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}