Quarkus Native and Container

Check the project's Quarkus version first. For generic (non-Quarkus) GraalVM work, use the optional java-add-graalvm-native-image-support skill if installed (otherwise see the GraalVM docs, https://www.graalvm.org/latest/reference-manual/native-image/).

Native build

# container build: no local GraalVM needed (Docker/Podman required)
./mvnw package -Dnative -Dquarkus.native.container-build=true
# local Mandrel/GraalVM (JAVA_HOME / GRAALVM_HOME must point to it)
./mvnw package -Dnative
# Gradle, Quarkus 3.10+ (add -Dquarkus.native.container-build=true without a local Mandrel)
./gradlew build -Dquarkus.native.enabled=true -Dquarkus.package.jar.enabled=false
# Gradle, older Quarkus
./gradlew build -Dquarkus.package.type=native

quarkus.package.type was deprecated in 3.10 (the 3.10 migration guide replaces it with quarkus.native.enabled and quarkus.package.jar.*); it is still accepted in 3.40 with a warning. Version gate verified with Gradle: on 3.9.5 -Dquarkus.native.enabled=true -Dquarkus.package.jar.enabled=false is ignored ("Unrecognized configuration key" warnings) and only a JVM quarkus-app is built, while -Dquarkus.package.type=native produces the native runner; on 3.10.0, 3.27.6 and 3.40.1 the new keys produce the native runner (3.10.0 also accepts the old key with the deprecation warning). The Maven native profile in the generated pom.xml already sets quarkus.native.enabled=true, quarkus.package.jar.enabled=false and skipITs=false when -Dnative is passed.

Local build verified on macOS arm64 with the Mandrel tarball for your Quarkus line from https://github.com/graalvm/mandrel/releases (mandrel-java25-macos-aarch64-25.0.4.1-Final.tar.gz for 3.40.1, extracted anywhere, JAVA_HOME pointing at its Contents/Home; Xcode command line tools are enough): 3.40.1 Maven package -Dnative took about 70 s and Gradle build with the two flags about 2.5 min; the runner is a Mach-O executable that starts in about 0.04 s, and ./mvnw verify -Dnative ran the *IT against it successfully. Quarkus checks the Mandrel/GraalVM version: 3.40 refuses 23.1 ("Out of date version of GraalVM or Mandrel detected ... Quarkus currently supports 25.0.0"), so use Mandrel 25 with 3.40 and mandrel-java21-macos-aarch64-23.1.12.1-Final with 3.27.6 (Maven verify -Dnative and Gradle both verified there).

Binary: target/*-runner (Maven) or build/*-runner (Gradle). A container build on macOS or Windows produces a Linux ELF that cannot run on the host: run it in a Linux container (for example docker run -v "$PWD/target:/w:ro" registry.access.redhat.com/ubi9/ubi-minimal /w/<name>-runner with the datasource passed through QUARKUS_DATASOURCE_* env vars), and note that ./mvnw verify -Dnative then fails in the *IT with Exit code is: '126'. Mandrel is Red Hat's GraalVM distribution for Quarkus; the container build pulls a Mandrel builder image matching the project (3.40.1 used quay.io/quarkus/ubi9-quarkus-mandrel-builder-image:jdk-25, Mandrel 25.0.4.1, about 2.5 minutes including the image pull); override it with quarkus.native.builder-image if needed. Native builds are slow and memory-hungry (several GB); do them in CI or on demand, not on every test run.

Common native failures

@RegisterForReflection(targets = ExternalDto.class)
public record ProductDto(String name) {}

…