hibernate/hibernate-orm · error · DuplicateMappingException

Duplicate named query '%s'

Error message

Duplicate named query '%s'

What it means

DuplicateMappingException(Type.QUERY): a named query is being registered under a name already present in either the HQL or the native-query map (checkQueryName checks both), so an @NamedQuery colliding with an @NamedNativeQuery is also a duplicate. Query names are global per SessionFactory/persistence unit. The duplicate always aborts bootstrap.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java:729

		if ( def == null ) {
			throw new IllegalArgumentException( "Named query definition is null" );
		}
		else if ( def.getRegistrationName() == null ) {
			throw new IllegalArgumentException( "Named query definition name is null: " + def.getHqlString() );
		}
		else if ( !defaultNamedQueryNames.contains( def.getRegistrationName() ) ) {
			applyNamedQuery( def.getRegistrationName(), def );
		}
	}

	private void applyNamedQuery(String name, NamedHqlQueryDefinition<?> query) {
		checkQueryName( name );
		namedQueryMap.put( name.intern(), query );
	}

	private void checkQueryName(String name) throws DuplicateMappingException {
		if ( namedQueryMap.containsKey( name ) || namedNativeQueryMap.containsKey( name ) ) {
			throw new DuplicateMappingException( DuplicateMappingException.Type.QUERY, name );
		}
	}

	@Override
	public void addDefaultQuery(NamedHqlQueryDefinition<?> queryDefinition) {
		applyNamedQuery( queryDefinition.getRegistrationName(), queryDefinition );
		defaultNamedQueryNames.add( queryDefinition.getRegistrationName() );
	}

	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	// Named native-query handling

	@Override
	public NamedNativeQueryDefinition<?> getNamedNativeQueryMapping(String name) {
		return namedNativeQueryMap.get( name );
	}

	@Override

View on GitHub (pinned to fad1729dce)

Solutions

  1. Search the project for the name shown in the message and rename one declaration — use a convention like EntityName.queryName
  2. Check persistence.xml for a mapping file listed twice and remove the duplicate entry
  3. If the duplicate lives in a third-party jar you cannot edit, isolate that mapping into its own persistence unit or exclude it from the factory
  4. Add a CI smoke test that builds the SessionFactory so duplicates surface at build time, not at deployment

Example fix

// before — two entities, same query name
@NamedQuery(name = "findActive", query = "select u from User u where u.active = true") // on User
@NamedQuery(name = "findActive", query = "select o from Ord o where o.open = true") // on Ord

// after
@NamedQuery(name = "User.findActive", query = "select u from User u where u.active = true")
@NamedQuery(name = "Ord.findActive", query = "select o from Ord o where o.open = true")
Defensive patterns

Strategy: validation

Validate before calling

static void assertNoDuplicateQueryNames( Class<?>... entityClasses ) {
    final Map<String, Class<?>> seen = new HashMap<>();
    for ( final Class<?> c : entityClasses ) {
        for ( final NamedQuery q : c.getAnnotationsByType( NamedQuery.class ) ) {
            final Class<?> prev = seen.put( q.name(), c );
            if ( prev != null ) {
                throw new IllegalStateException( "Duplicate @NamedQuery '" + q.name() + "' on " + prev + " and " + c );
            }
        }
        for ( final NamedNativeQuery q : c.getAnnotationsByType( NamedNativeQuery.class ) ) {
            final Class<?> prev = seen.put( q.name(), c );
            if ( prev != null ) {
                throw new IllegalStateException( "Duplicate native query name '" + q.name() + "' on " + prev + " and " + c );
            }
        }
    }
}

Try / catch

try {
    sessionFactory = metadata.buildSessionFactory();
} catch ( DuplicateMappingException e ) {
    if ( e.getType() == DuplicateMappingException.Type.QUERY ) {
        throw new IllegalStateException( "Duplicate named query '" + e.getName() + "' — rename one declaration", e );
    }
    throw e;
}

Prevention

When it happens

Trigger: Two @NamedQuery(name="X") annotations in one persistence unit; an @NamedQuery and an @NamedNativeQuery sharing a name; hbm.xml <query name="X"> duplicated by an annotation; the same orm.xml listed twice in persistence.xml; two library jars each defining the same query name.

Common situations: Copy-pasted entities, shared 'common model' jars reused across apps, and the Hibernate 5-to-6 upgrade where previously tolerated duplicate query names now fail fast; also mixing annotations with leftover hbm.xml mappings of the same classes.

Related errors

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