hibernate/hibernate-orm · error · AnnotationException

Class or package level '@NamedStoredProcedureQuery' annotati

Error message

Class or package level '@NamedStoredProcedureQuery' annotation must specify a 'name'

What it means

QueryBinder.bindNamedStoredProcedureQuery registers a jakarta.persistence @NamedStoredProcedureQuery; if namedStoredProcedureQuery.name() is blank, AnnotationException is thrown during metadata building. The name is the key later passed to createNamedStoredProcedureQuery(name), so it cannot be empty.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/model/internal/QueryBinder.java:975

			}

			if ( BOOT_LOGGER.isTraceEnabled() ) {
				BOOT_LOGGER.bindingNamedQuery( registrationName,
						namedQuery.query().replace( '\n', ' ' ) );
			}

			final var definition = NamedHqlSelectionDefinitionImpl.from( namedQuery, location );
			context.getMetadataCollector().addNamedQuery( definition );
		}
	}

	public static void bindNamedStoredProcedureQuery(
			NamedStoredProcedureQuery namedStoredProcedureQuery,
			MetadataBuildingContext context,
			boolean isDefault) {
		if ( namedStoredProcedureQuery != null ) {
			if ( namedStoredProcedureQuery.name().isBlank() ) {
				throw new AnnotationException( "Class or package level '@NamedStoredProcedureQuery' annotation must specify a 'name'" );
			}

			final var definition = new NamedProcedureCallDefinitionImpl( namedStoredProcedureQuery );
			final var collector = context.getMetadataCollector();
			if ( isDefault ) {
				collector.addDefaultNamedProcedureCall( definition );
			}
			else {
				collector.addNamedProcedureCallDefinition( definition );
			}
			BOOT_LOGGER.boundStoredProcedureQuery(
					definition.getRegistrationName(),
					definition.getProcedureName() );
		}
	}

	public static void bindSqlResultSetMapping(
			SqlResultSetMapping resultSetMappingAnn,

View on GitHub (pinned to fad1729dce)

Solutions

1. Set a unique non-blank name, conventionally EntityName.procedureName.
2. If names come from generated sources, fix the generator/template to always emit the key.
3. Audit orm.xml files too when annotations look correct but the error persists.

Example fix

// before
@NamedStoredProcedureQuery(name = "", procedureName = "SP_CALC_TOTALS")

// after
@NamedStoredProcedureQuery(name = "Order.calcTotals", procedureName = "SP_CALC_TOTALS")

@Test void procedureQueriesHaveNames() {
    NamedStoredProcedureQuery q = Order.class.getAnnotation(NamedStoredProcedureQuery.class);
    if (q != null) assertTrue(!q.name().isBlank());
}

try {
    metadata = sources.buildMetadata();
} catch (AnnotationException e) {
    failBuild("Named procedure query registration failed: " + e.getMessage());
}

When it happens

Trigger: @NamedStoredProcedureQuery(name = "", procedureName = "SP_DO_WORK") on an entity or in orm.xml equivalent; blank (empty/whitespace) name triggers the check before the procedure definition is registered.

Common situations: Wrapping legacy stored procedures and leaving the registration name for later; code-generating procedure mappings with an unfilled template; refactoring that moves procedureName but clears name.

Related errors

• Class or package level '@NamedQuery' annotation must specify
• NamedStoredProcedureQuery [%s] specified both resultClasses
• Class or package level '@NamedStatement' annotation must spe
• Class or package level '@NamedNativeQuery' annotation must s
• Named query definition is null

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/0f1bb3990fe70162. Report an issue: GitHub.