hibernate/hibernate-orm · error · IllegalArgumentException

illegal collection interface type

Error message

illegal collection interface type

What it means

Hibernate.collection(Class) returns a CollectionInterface factory for the six collection interfaces Hibernate knows how to instantiate persistently: List, Set, Map, SortedMap, SortedSet and Collection (bag). Passing any other Class (e.g. Queue, Deque, a custom interface, or an implementation class like ArrayList) falls through the if-chain to IllegalArgumentException('illegal collection interface type').

Source

Thrown at hibernate-core/src/main/java/org/hibernate/Hibernate.java:593

			return (CollectionInterface<C>) list();
		}
		else if (collectionClass == Set.class) {
			return (CollectionInterface<C>) set();
		}
		else if (collectionClass == Map.class) {
			return (CollectionInterface<C>) map();
		}
		if (collectionClass == SortedMap.class) {
			return (CollectionInterface<C>) sortedMap();
		}
		else if (collectionClass == SortedSet.class) {
			return (CollectionInterface<C>) sortedSet();
		}
		else if (collectionClass == Collection.class) {
			return (CollectionInterface<C>) bag();
		}
		else {
			throw new IllegalArgumentException("illegal collection interface type");
		}
	}

	/**
	 * Obtain a {@linkplain LobHelper} for instances of {@link java.sql.Blob}
	 * and {@link java.sql.Clob}.
	 *
	 * @return an instance of {@link LobHelper}
	 *
	 * @since 7.1
	 */
	public static LobHelper getLobHelper() {
		return lobHelper;
	}

	private static PersistentAttributeInterceptor getAttributeInterceptor(Object entity) {
		return asPersistentAttributeInterceptable( entity ).$$_hibernate_getInterceptor();
	}

View on GitHub (pinned to fad1729dce)

Solutions

1. Pass one of the six supported interfaces: List.class, Set.class, Map.class, SortedMap.class, SortedSet.class, or Collection.class.
2. Map unsupported types to a supported supertype (Queue/Deque -> List or Collection) and convert when reading.
3. Call the specific factory directly: Hibernate.list(), Hibernate.set(), Hibernate.map(), Hibernate.sortedSet(), Hibernate.sortedMap(), Hibernate.bag().
4. Guard with a type check before calling (see defense) when the class comes from reflection.

Example fix

// before - throws: Queue is not supported
CollectionInterface<Queue<Task>> ci = Hibernate.collection(Queue.class);

// after - map to a supported interface
CollectionInterface<List<Task>> ci = Hibernate.collection(List.class);

private static final Set<Class<?>> SUPPORTED = Set.of(List.class, Set.class, Map.class,
        SortedMap.class, SortedSet.class, Collection.class);

if (!SUPPORTED.contains(collectionClass)) {
    throw new IllegalArgumentException("Unsupported collection interface: " + collectionClass
            + "; expected one of " + SUPPORTED);
}

static boolean isSupportedCollectionInterface(Class<?> c) {
    return c == List.class || c == Set.class || c == Map.class
        || c == SortedMap.class || c == SortedSet.class || c == Collection.class;
}

try {
    return Hibernate.collection(collectionClass);
} catch (IllegalArgumentException e) {
    if (e.getMessage().equals("illegal collection interface type")) {
        return Hibernate.collection(Collection.class); // degrade to bag semantics
    }
    throw e;
}

When it happens

Trigger: Calling Hibernate.collection(Queue.class), Hibernate.collection(Deque.class) or Hibernate.collection(ArrayList.class) - i.e. any class reference that is not exactly List/Set/Map/SortedMap/SortedSet/Collection.

Common situations: Generic utility code that derives the collection interface from a field type or generic parameter (which may be Queue or a custom type); migrating code from Hibernate.collectionInterfaceFor-style helpers; passing implementation classes instead of interfaces.

Related errors

• cannot recreate collection while filter is enabled: " + coll
• cannot recreate collection while filter is enabled [%s : %s]
• Attribute was neither a Collection nor a Map : ${erasedType}
• Sets don't have indexes
• Sets don't support updating by element

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