{"record":{"id":"a248ab8f10d8cacb","repo":"hibernate/hibernate-orm","slug":"entitypersister-implementation-classname-does-a248ab","errorCode":null,"errorMessage":"EntityPersister implementation '{className}' does not support 'UniqueKeyLoadable'","messagePattern":"EntityPersister implementation '(.+?)' does not support 'UniqueKeyLoadable'","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/persister/entity/EntityPersister.java","lineNumber":638,"sourceCode":"\tdefault Object load(Object id, Object optionalObject, LockOptions lockOptions, SharedSessionContractImplementor session, Boolean readOnly)\n\t\t\tthrows HibernateException {\n\t\treturn load( id, optionalObject, lockOptions, session );\n\t}\n\n\t/**\n\t * Performs a load of multiple entities (of this type) by identifier simultaneously.\n\t *\n\t * @param ids The identifiers to load\n\t * @param session The originating Session\n\t * @param loadOptions The options for loading\n\t *\n\t * @return The loaded, matching entities\n\t */\n\tList<?> multiLoad(Object[] ids, SharedSessionContractImplementor session, MultiIdLoadOptions loadOptions);\n\n\t@Override\n\tdefault Object loadByUniqueKey(String propertyName, Object uniqueKey, SharedSessionContractImplementor session) {\n\t\tthrow new UnsupportedOperationException(\n\t\t\t\t\"EntityPersister implementation '\" + getClass().getName()\n\t\t\t\t\t\t+ \"' does not support 'UniqueKeyLoadable'\"\n\t\t);\n\t}\n\n\t/**\n\t * Do a version check (optional operation)\n\t */\n\tvoid lock(Object id, Object version, Object object, LockMode lockMode, SharedSessionContractImplementor session);\n\n\t/**\n\t * Do a version check (optional operation)\n\t */\n\tvoid lock(Object id, Object version, Object object, LockOptions lockOptions, SharedSessionContractImplementor session);\n\n\t/**\n\t * Persist an instance\n\t *","sourceCodeStart":620,"sourceCodeEnd":656,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/persister/entity/EntityPersister.java#L620-L656","documentation":"EntityPersister.loadByUniqueKey loads an entity by a unique key instead of its primary key — the path used when a @ManyToOne is resolved against a non-PK unique column (legacy property-ref / referenced-property associations, EntityType.loadByUniqueKey at type/EntityType.java:703). The interface default throws UnsupportedOperationException('EntityPersister implementation ... does not support UniqueKeyLoadable'); AbstractEntityPersister (line 2669) provides the real implementation, so only custom persisters missing the override fail.","triggerScenarios":"Resolving a to-one association mapped to a unique-key column when the target entity's persister is a custom implementation without a loadByUniqueKey override; direct calls to persister.loadByUniqueKey(...) or EntityUniqueKey-based lookups.","commonSituations":"Custom persisterClass on the association target; legacy property-ref style associations modernized to annotations but still unique-key based; stub persisters in tests.","solutions":["Add a loadByUniqueKey override to the custom persister, following AbstractEntityPersister's implementation","Map the association to the target's primary key instead of the unique column","Drop the custom persister for the target entity"],"exampleFix":"// before: association targets a unique (non-PK) column and target uses a custom persister\n@ManyToOne\n@JoinColumn(name = \"sku\", referencedColumnName = \"sku\") // sku is unique, not the PK\nprivate Product product; // Product has custom @Persister -> loadByUniqueKey fails\n\n// after: reference the primary key\n@ManyToOne\n@JoinColumn(name = \"product_id\", referencedColumnName = \"id\")\nprivate Product product;","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"static boolean supportsUniqueKeyLoad(EntityPersister persister) {\n    return persister instanceof org.hibernate.persister.entity.AbstractEntityPersister; // implements loadByUniqueKey\n}","tryCatchPattern":"try {\n    return persister.loadByUniqueKey(propertyName, value, session);\n}\ncatch ( UnsupportedOperationException e ) {\n    // message names the persister class and 'UniqueKeyLoadable'\n    throw new IllegalStateException(\"Association target cannot be loaded by unique key: \" + e.getMessage(), e);\n}","preventionTips":["Map associations to primary keys unless a unique-key reference is unavoidable","If using custom persisters, keep a checklist of EntityPersister methods to override (loadByUniqueKey, natural-id loaders, merge coordinator)","Add an integration test that eagerly resolves every association to catch load-path gaps at build time"],"tags":["hibernate","orm","unique-key","associations","persister","api-unsupported"],"backgroundTag":"unique-key-load-unsupported","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}