hibernate/hibernate-orm · error · UnsupportedOperationException

Not supported.

Error message

Not supported.

What it means

NestedJarDescriptor.resolveJarFileReference unconditionally throws UnsupportedOperationException because an archive that is itself nested (jar:...!/...) cannot, in turn, resolve further <jar-file/> references. You only reach it when Hibernate processes a jar-file reference while the current archive descriptor is a nested jar.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/archive/internal/NestedJarDescriptor.java:122

										archiveUrl,
										jarEntry.getName()
								),
								e
						);
					}
				}
			}
		}
		catch (IOException e) {
			throw new ArchiveException( "Error accessing nested jar archive [" + archiveUrl + "]", e );
		}

		return null;
	}

	@Override @Nonnull
	public ArchiveDescriptor resolveJarFileReference(@Nonnull String jarFileReference) {
		throw new UnsupportedOperationException( "Not supported." );
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

1. Remove the <jar-file/> entry from the persistence unit inside the nested archive
2. Repackage so the persistence unit and the jars it lists are top-level sibling archives
3. Replace <jar-file/> with explicit <class> entries or rely on automatic entity scanning

Example fix

// before (persistence.xml inside a nested jar, e.g. BOOT-INF/classes/META-INF/persistence.xml)
<jar-file>entities.jar</jar-file>

// after: list entities explicitly
<class>com.acme.entity.Customer</class>
<class>com.acme.entity.Order</class>

// guard: a persistence unit reached through a nested-jar URL must not declare <jar-file/>
var puUrl = clazz.getResource("/META-INF/persistence.xml");
if (puUrl != null && "jar".equals(puUrl.getProtocol())
        && puUrl.toString().contains("!/")
        && readText(puUrl).contains("<jar-file")) {
    throw new IllegalStateException(
        "persistence.xml inside a nested archive must not use <jar-file/>; use <class> entries");
}

try {
    ArchiveDescriptor resolved = descriptor.resolveJarFileReference(ref);
} catch (UnsupportedOperationException e) {
    throw new IllegalArgumentException(
        "Cannot resolve <jar-file/> " + ref + " from a nested archive; repackage as top-level jars", e);
}

When it happens

Trigger: A persistence unit whose scanning root is a nested jar (e.g. jar:file:app.jar!/WEB-INF/classes/) that itself declares a <jar-file/> entry; or SPI-level code calling ArchiveDescriptor.resolveJarFileReference on a descriptor built from a nested-jar URL.

Common situations: Executable/fat jars (Spring Boot) where persistence.xml lives inside a nested archive and still lists <jar-file/> entries copied from a legacy WAR layout; unusual EAR packaging after migration.

Related errors

• format() function not supported on Sybase
• Decomposition not supported for %s
• Unknown type of binding : <bindingRoot>
• Could not resolve jar-file: <jarFileReference>
• Unable to resolve <jar-file/> reference - {}

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