{"record":{"id":"7ba2fb941cf52801","repo":"hibernate/hibernate-orm","slug":"could-not-resolve-nativequery-parameter-type-s","errorCode":null,"errorMessage":"Could not resolve NativeQuery parameter type : `%s`","messagePattern":"Could not resolve NativeQuery parameter type : `(.+?)`","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/sql/exec/internal/JdbcParameterBindingsImpl.java","lineNumber":118,"sourceCode":"\t}\n\n\tprivate JdbcMapping jdbcMapping(\n\t\t\tSessionFactoryImplementor factory,\n\t\t\tQueryParameterImplementor<?> param,\n\t\t\tQueryParameterBinding<?> binding) {\n\t\tfinal var type = determineParamType( param, binding );\n\t\tif ( type == null ) {\n\t\t\treturn factory.getTypeConfiguration().getBasicTypeForJavaType( Object.class );\n\t\t}\n\t\telse if ( type instanceof BasicTypeReference<?> basicTypeReference ) {\n\t\t\treturn factory.getTypeConfiguration().getBasicTypeRegistry()\n\t\t\t\t\t.resolve( basicTypeReference );\n\t\t}\n\t\telse if ( type instanceof BasicValuedMapping basicValuedMapping ) {\n\t\t\treturn basicValuedMapping.getJdbcMapping();\n\t\t}\n\t\telse {\n\t\t\tthrow new IllegalArgumentException( \"Could not resolve NativeQuery parameter type : `\" + param + \"`\");\n\t\t}\n\t}\n\n\tprivate BindableType<?> determineParamType(QueryParameterImplementor<?> param, QueryParameterBinding<?> binding) {\n\t\tfinal var type = binding.getBindType();\n\t\treturn type == null ? param.getHibernateType() : type;\n\t}\n\n\t@Override\n\tpublic void addBinding(JdbcParameter parameter, JdbcParameterBinding binding) {\n\t\tif ( bindingMap == null ) {\n\t\t\tbindingMap = new IdentityHashMap<>();\n\t\t}\n\t\tbindingMap.put( parameter, binding );\n\t}\n\n\t@Override\n\tpublic Collection<JdbcParameterBinding> getBindings() {","sourceCodeStart":100,"sourceCodeEnd":136,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/sql/exec/internal/JdbcParameterBindingsImpl.java#L100-L136","documentation":"While preparing parameter bindings for a native query, JdbcParameterBindingsImpl derives each parameter's JdbcMapping from the QueryParameterBinding's bind type or the QueryParameter's Hibernate type. If that type is neither a BasicTypeReference nor a BasicValuedMapping - e.g. an entity/embedded type or an arbitrary object - it throws IllegalArgumentException('Could not resolve NativeQuery parameter type'). Native SQL parameters must map to single-column basic types.","triggerScenarios":"nativeQuery.setParameter(p, entityInstance) or binding an embedded/array value; setParameter with a custom Type that is not basic-valued; using a QueryParameter whose Hibernate type is an EntityType (association passed as a native query parameter).","commonSituations":"Mixing HQL-style entity parameters into native SQL; migrating an HQL query to native SQL while keeping entity-typed parameters; custom UserType implementations that do not implement BasicValuedMapping.","solutions":["Bind a basic value instead - pass the entity's identifier: query.setParameter(\"p\", entity.getId())","Give the parameter an explicit basic type: setParameter(\"p\", value, StandardBasicTypes.LONG)","For custom types, implement BasicValuedMapping or register a BasicTypeReference for them","Use the createNativeQuery overloads taking Object[]/Type[] so parameter types are supplied up front"],"exampleFix":"// before\nNativeQuery<?> q = session.createNativeQuery(\"select * from Orders o where o.customerId = :c\");\nq.setParameter( \"c\", customer ); // entity instance -> throws\n\n// after\nq.setParameter( \"c\", customer.getId() );","handlingStrategy":"validation","validationCode":"// native query parameters must be basic-typed\nObject v = value instanceof EntityProxy proxy ? proxy.getIdentifier() : value;\nnativeQuery.setParameter( name, v );","typeGuard":"boolean isNativeParameterSafe(Object value) {\n    return value == null\n        || value instanceof String || value instanceof Number || value instanceof Boolean\n        || value instanceof java.time.temporal.Temporal || value instanceof byte[]\n        || value instanceof java.util.UUID || value instanceof Enum;\n}","tryCatchPattern":null,"preventionTips":["Pass ids/basic values to native queries, never entities or embeddables","Give explicit basic types when binding: setParameter(name, value, StandardBasicTypes.X)","Make custom UserTypes implement BasicValuedMapping if they must be usable as native parameters"],"tags":["hibernate","orm","native-query","parameter-binding","illegal-argument"],"backgroundTag":"native-query-parameter-type","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}