hibernate/hibernate-orm · error · DuplicateMappingException

Duplicate named entity graph '%s'

Error message

Duplicate named entity graph '%s'

What it means

Named entity graphs are registered by name; addNamedEntityGraph throws DuplicateMappingException(Type.NAMED_ENTITY_GRAPH) with 'Duplicate named entity graph' when a graph with that name is already registered - two @NamedEntityGraph / @NamedEntityGraphs (or XML <named-entity-graph>) declarations share one name.

Source

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

	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	// Named EntityGraph handling

	@Override
	public NamedEntityGraphDefinition getNamedEntityGraph(String name) {
		return namedEntityGraphMap.get( name );
	}

	@Override
	public Map<String, NamedEntityGraphDefinition> getNamedEntityGraphs() {
		return namedEntityGraphMap;
	}

	@Override
	public void addNamedEntityGraph(NamedEntityGraphDefinition definition) {
		final String name = definition.name();
		final var previous = namedEntityGraphMap.put( name, definition );
		if ( previous != null ) {
			throw new DuplicateMappingException( DuplicateMappingException.Type.NAMED_ENTITY_GRAPH, name );
		}
	}


	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	// Named query handling

	public NamedHqlQueryDefinition<?> getNamedHqlQueryMapping(String name) {
		if ( name == null ) {
			throw new IllegalArgumentException( "null is not a valid query name" );
		}
		return namedQueryMap.get( name );
	}

	@Override
	public void visitNamedHqlQueryDefinitions(Consumer<NamedHqlQueryDefinition<?>> definitionConsumer) {
		namedQueryMap.values().forEach( definitionConsumer );
	}

View on GitHub (pinned to fad1729dce)

Solutions

1. Rename one of the graphs named in the message to be unique and update lookups (EntityManager.getEntityGraph(name))
2. Delete the duplicated graph declaration if it was accidental
3. Consolidate: define shared graphs once and reference them rather than redefining per entity

Example fix

// before
@NamedEntityGraph(name = "overview", ...)  // on User
@NamedEntityGraph(name = "overview", ...)  // on Order -> throws

// after
@NamedEntityGraph(name = "User.overview", ...)
@NamedEntityGraph(name = "Order.overview", ...)

// Pre-check programmatic graph registration
if (metadata.getNamedEntityGraphs().containsKey(graph.name())) {
    throw new IllegalStateException("entity graph name already used: " + graph.name());
}

try {
    metadata.buildSessionFactory();
}
catch (DuplicateMappingException e) {
    // message names the duplicated graph: rename one @NamedEntityGraph
    // and update EntityManager.getEntityGraph(name) call sites
}

When it happens

Trigger: The same @NamedEntityGraph(name="...") appearing on two entities or twice in an @NamedEntityGraphs container; duplicate <named-entity-graph name=...> entries in orm.xml; or programmatic double registration hitting the put-then-check at InFlightMetadataCollectorImpl.java:685-690.

Common situations: Copy-pasted graph annotations; merged modules defining generic 'overview'/'detail' graphs with identical names; refactoring that moved annotations without renaming them.

Related errors

• Entity classes [%s] and [%s] share the entity name '%s' (ent
• Duplicate generator name '%s'; you will likely want to set t
• The 'root' parameter of the @NamedEntityGraph should be pass
• The 'root' parameter of the @NamedEntityGraph annotation mus
• Cannot mutate immutable graph node

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