{"record":{"id":"fb09d7ac83e374eb","repo":"hibernate/hibernate-orm","slug":"could-not-instantiate-entity-fb09d7","errorCode":null,"errorMessage":"Could not instantiate entity","messagePattern":"Could not instantiate entity","errorType":"exception","errorClass":"InstantiationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/metamodel/internal/EmbeddableInstantiatorRecordIndirecting.java","lineNumber":47,"sourceCode":"\t\t\t\t: new EmbeddableInstantiatorRecordIndirecting( javaType, index );\n\t}\n\n\t@Override\n\tpublic Object instantiate(ValueAccess valuesAccess) {\n\t\tif ( constructor == null ) {\n\t\t\tthrow new InstantiationException( \"Unable to locate constructor for embeddable\", getMappedPojoClass() );\n\t\t}\n\n\t\ttry {\n\t\t\tfinal var originalValues = valuesAccess.getValues();\n\t\t\tfinal var values = new Object[originalValues.length];\n\t\t\tfor ( int i = 0; i < values.length; i++ ) {\n\t\t\t\tvalues[i] = originalValues[index[i]];\n\t\t\t}\n\t\t\treturn constructor.newInstance( values );\n\t\t}\n\t\tcatch ( Exception e ) {\n\t\t\tthrow new InstantiationException( \"Could not instantiate entity\", getMappedPojoClass(), e );\n\t\t}\n\t}\n\n\t// Handles gaps, by leaving the value null for that index\n\tprivate static class EmbeddableInstantiatorRecordIndirectingWithGap\n\t\t\textends EmbeddableInstantiatorRecordIndirecting {\n\n\t\tpublic EmbeddableInstantiatorRecordIndirectingWithGap(Class<?> javaType, int[] index) {\n\t\t\tsuper( javaType, index );\n\t\t}\n\n\t\t@Override\n\t\tpublic Object instantiate(ValueAccess valuesAccess) {\n\t\t\tif ( constructor == null ) {\n\t\t\t\tthrow new InstantiationException( \"Unable to locate constructor for embeddable\", getMappedPojoClass() );\n\t\t\t}\n\n\t\t\ttry {","sourceCodeStart":29,"sourceCodeEnd":65,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/metamodel/internal/EmbeddableInstantiatorRecordIndirecting.java#L29-L65","documentation":"Hibernate throws this org.hibernate.InstantiationException while materializing an embeddable mapped as a Java record, when the record's canonical constructor invocation fails. This instantiator (EmbeddableInstantiatorRecordIndirecting) re-orders the values read from the database into record-component order using its index array and then calls constructor.newInstance(values); any exception thrown by that call (NPE from validation, failed unboxing, IllegalAccessException in modular setups) is wrapped in this InstantiationException with the original as its cause.","triggerScenarios":"Loading or querying a row into an @Embedded/@EmbeddedId record whose compact constructor throws (e.g. Objects.requireNonNull) because a mapped column is null; a record component declared as a primitive (int, boolean) receiving a null column value causing NullPointerException during unboxing; the record living in a Java module (module-info) that does not open its package to hibernate.core, making the canonical constructor inaccessible via reflection.","commonSituations":"Teams adopting Java records for embeddables with null-validation in compact constructors while the schema still allows NULLs; migrating embeddable fields from wrapper types to primitives; JPQL/Criteria loads of entities containing such embeddables; strong encapsulation under JPMS after moving entities into named modules.","solutions":["Inspect the cause chain of the InstantiationException (getCause()) - it names the real constructor failure","If columns can be null, use wrapper types in the record and remove null-rejecting checks (Objects.requireNonNull) from the compact constructor","Declare columns NOT NULL in the schema if the record genuinely must reject nulls","Register a custom instantiator with @org.hibernate.annotations.EmbeddableInstantiator (or @IdMappedInstantiator for id embeddables) that converts raw values defensively before calling the constructor","If running under JPMS, add 'opens <entity.package> to hibernate.core' (or hibernate.orm.core) in module-info.java"],"exampleFix":"// before - compact constructor rejects nulls from nullable columns\npublic record Address(String street, String zip) {\n    public Address {\n        Objects.requireNonNull(street);\n    }\n}\n\n// after - tolerate nulls, or provide a custom instantiator\npublic record Address(String street, String zip) {\n}\n\n// or, map a default with a custom instantiator\npublic class AddressInstantiator implements EmbeddableInstantiator {\n    @Override\n    public Object instantiate(ValueAccess valuesAccess) {\n        Object[] v = valuesAccess.getValues();\n        return new Address( v[0] == null ? \"\" : (String) v[0], (String) v[1] );\n    }\n}\n\n@Embeddable\n@EmbeddableInstantiator(AddressInstantiator.class)\npublic record Address(String street, String zip) {}","handlingStrategy":"try-catch","validationCode":"// Before loading, verify nullable columns match null-tolerant record components\nboolean safe = true;\nfor (RecordComponent rc : Address.class.getRecordComponents()) {\n    if ( rc.getType().isPrimitive() && columnNullable( rc.getName() ) ) safe = false;\n}\nif ( !safe ) throw new IllegalStateException(\"Primitive record component mapped to nullable column\");","typeGuard":null,"tryCatchPattern":"try {\n    return session.find(User.class, id);\n}\ncatch ( org.hibernate.InstantiationException e ) {\n    // e.getCause() holds the real constructor failure (NPE, IllegalArgument, ...)\n    log.warn(\"Row {} has embeddable data the record rejects: {}\", id, e.getCause());\n    return null;\n}","preventionTips":["Avoid null-rejecting checks in record compact constructors; validate at use sites instead","Use wrapper types (Integer, Long, Boolean) for record components backed by nullable columns","Enforce NOT NULL on columns whose record components must never be null","Write a repository test that loads one row of every embeddable-owning entity"],"tags":["hibernate","jpa","embeddable","record","instantiation","null-handling"],"backgroundTag":"jpa-embeddable-instantiation-failed","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}