Native image + Spring Boot 4: how to run Pulsar admin/topic auto-creation (shaded breaks on native-build-tools 1.x, non-shaded hits javax.ws.rs vs jakarta.ws.rs)?

[JeffHu88]

TL;DR

On GraalVM native image with Spring Boot 4 + native-build-tools (native-maven-plugin) 1.x, getting Spring Pulsar's admin / topic auto-creation (PulsarAdministration) to work seems to require either staying on the shaded pulsar-client-all (which 1.x breaks) or switching to the non-shaded admin client (which then conflicts with Spring Boot 4's jakarta.ws.rs). I'd like to know the recommended setup.

Environment

• Spring Boot 4.0.6 (spring-boot-starter-parent) / Spring Pulsar via spring-boot-starter-pulsar
• Apache Pulsar client 4.2.1
• GraalVM CE 25, Java 25
• org.graalvm.buildtools:native-maven-plugin

Context

A CDC bridge (Pulsar consumer → ClickHouse) built as a native image. We declare PulsarTopic
beans (partitioned topics with specific partition counts), so at startup
PulsarAdministration.createOrModifyTopicsIfNeeded(...) builds a PulsarAdmin.

The chain of problems we hit

1. Baseline that worked: native-maven-plugin 0.11.5 + the default shaded pulsar-client-all.
   The native binary started fine; admin/topic-creation worked. (Shaded Jersey/Netty are relocated
   under org.apache.pulsar.shade.*, self-contained.)

2. After bumping native-maven-plugin to 1.x, the shaded client breaks at native runtime:

   NoClassDefFoundError: Could not initialize class
   org.apache.pulsar.shade.io.netty.util.internal.PlatformDependent
   

   The new reachability-metadata format in native-build-tools 1.x no longer supplies metadata for
   the shaded Netty package (org.apache.pulsar.shade.io.netty.*), so PlatformDependent.<clinit>
   (reflective Unsafe/Cleaner setup) fails.

3. To fix that, we switch to the non-shaded pulsar-client-original + pulsar-client-admin-original
   (real io.netty.*, which ships its own native-image metadata). Netty is now fine, but the
   non-shaded admin client uses Jersey 2.x / javax.ws.rs, which collides with Spring Boot 4's
   BOM-managed jakarta.ws.rs-api:4.0.0 + Jersey 4.0.2:

   Could not initialize class org.apache.pulsar.client.admin.internal.PulsarAdminImpl
   # underlying: ClassNotFoundException: javax.ws.rs.core.Configuration
   

   We can only get past it by pinning Jersey back to 2.x (jersey-bom:2.42 + jakarta.ws.rs-api:2.1.6),
   re-adding the javax.* deps, and supplying a large tracing-agent-captured reachability metadata
   set for the Jersey/HK2 admin request path — which feels very brittle against Spring Boot 4.

Questions

1. What is the recommended way to run Spring Pulsar's admin / topic auto-creation
   (PulsarAdministration) in a GraalVM native image on Spring Boot 4 + native-build-tools 1.x?
2. Is the shaded pulsar-client-all still expected to work in native under native-build-tools 1.x,
   or is non-shaded now the only supported route?
3. If non-shaded is the way forward, is the Jersey 2.x / javax.ws.rs vs Spring Boot 4 jakarta.ws.rs
   conflict known? Is there a supported approach (e.g. ship native hints for the admin path, or
   guidance to disable PulsarAdministration and pre-create topics via broker allowAutoTopicCreation)?
4. Any plan for the Pulsar admin client to move to jakarta.ws.rs?

Thanks for any pointers!

[JeffHu88]

Resolved — turned out to be a misdiagnosis on our side, not a Spring Pulsar issue. Posting the resolution in case it helps others.

Staying on the shaded pulsar-client-all is the right setup for native, and it works on both native-build-tools 0.11.5 and 1.1.x — as long as the shaded Netty package is run-time-initialized:

--initialize-at-run-time=io.netty,com.lmax.disruptor,org.apache.pulsar,org.apache.pulsar.shade.io.netty

(with <metadataRepository><enabled>true). With that entry, PlatformDependent.<clinit> no longer fails and PulsarAdministration topic auto-creation reaches the broker normally in the native image.

We had switched to the non-shaded pulsar-client-original + pulsar-client-admin-original to "fix" a PlatformDependent failure that was actually caused by the missing run-time-init entry — not by native-build-tools 1.x. Going non-shaded is what pulled in the un-shaded Jersey 2.x (javax.ws.rs) admin client and created the jakarta.ws.rs conflict with Spring Boot 4, which then needed a Jersey 2.x pin + javax.* deps + hand-written reachability metadata. Reverting to the shaded client removed all of that.

Recommendation for Spring Boot 4 native users: keep the shaded pulsar-client-all and add org.apache.pulsar.shade.io.netty to --initialize-at-run-time. No Jersey/jakarta workaround needed.

[JeffHu88]

Correction / root cause found. My earlier answer was wrong — the native-build-tools plugin version does matter, and the cause is the GraalVM Reachability Metadata Repository (<metadataRepository>), not the shaded-vs-non-shaded choice.

Setup: Spring Boot 4.0.6, GraalVM CE 25, Pulsar via the default shaded pulsar-client-all, --initialize-at-run-time=...,org.apache.pulsar.shade.io.netty.

Symptom on Linux native runtime (works on the JVM, and the same binary only WARNs on macOS):

NoClassDefFoundError: Could not initialize class org.apache.pulsar.shade.io.netty.util.internal.PlatformDependent
  at ...NioEventLoop.<clinit> ... PulsarClientImpl.<init> (building the EventLoopGroup)

Evidence (via mvn -Pnative native:write-args-file, diffing the generated native-image argfile):

• native-maven-plugin 0.11.5 vs 1.1.1, both with metadataRepository enabled → the argfiles differ in exactly one line: -H:ConfigurationFileDirectories=.... Every other arg (including our --initialize-at-run-time) is byte-identical.
• 0.11.5 matches ~15 artifacts; 1.1.1 matches ~90, including org.apache.pulsar:pulsar-client-api, org.apache.pulsar:bouncy-castle-bc, and the Linux-only netty-transport-native-epoll / netty-transport-classes-epoll / netty-transport-native-unix-common metadata.
• Setting <metadataRepository><enabled>false</enabled> on 1.1.1 removes that line entirely (and the related --exclude-config entries) — the difference vanishes.

So native-build-tools 1.0 (new reachability-metadata.json format + 1.0-M1 repo) now matches far more of the dependency graph and applies much broader reflection/resource/JNI metadata. That metadata carries no class-initialization directives, but per the GraalVM metadata docs it changes which types are reachable at build time, which in turn shifts initialization analysis — enough to make the shaded netty PlatformDependent clinit throw at runtime on Linux. macOS masks it (the underlying Unsafe::allocateMemory is only a warning there).

Fix (both now verified on a Linux dev cluster):

• Option A — adopted: upgrade to native-maven-plugin 1.1.1 and set <metadataRepository><enabled>false</enabled>. Removes the trigger entirely; native-image then relies on jar-bundled META-INF/native-image + Spring AOT (+ your own hint registrars). Confirmed working on Linux.
• Option B: pin native-maven-plugin to 0.11.5 (keeps the metadata repo enabled). Also works on Linux.

We went with Option A to stay on the latest plugin. The trade-off is giving up the GraalVM Reachability Metadata Repository, which is acceptable for us since the app already ships explicit hint registrars; projects that lean on the repo for third-party metadata should weigh that before disabling it.

Question for maintainers: is this expected with the 1.0 metadata repo + shaded pulsar-client-all, and is the recommendation to disable the repo, or is there metadata that should be excluded for the shaded Pulsar client?

---

Why this class specifically, and why only on Linux — grounded in the GraalVM compatibility guide:

• Our run-time init choice is the documented default — "By default, classes are initialized at run time." So this is not a build-time-init-breaks-assumptions problem; it's a genuine run-time <clinit> throw.
• PlatformDependent.<clinit> probes sun.misc.Unsafe / direct memory. The compatibility guide lists Unsafe Memory Access under "Features That May Operate Differently" ("Native Image implements some Java features differently to the Java VM"). So this clinit sits on a known platform-fragile path — which is exactly why the same binary passes on macOS (where the underlying sun.misc.Unsafe::allocateMemory is only a warning) and throws on Linux.
• Under the closed-world assumption ("all code is known at build time ... no new code is loaded at run time"), the broader conditional metadata that the 1.0 repo applies changes build-time reachability/analysis — enough to tip this already-fragile Unsafe-dependent clinit over on Linux.
• One gap worth flagging: the metadata repo serves netty 4.1.x metadata while the actual classpath has netty 4.2.12 (pulled by webflux/rsocket/reactor-netty), and metadataRepository also emits --exclude-config to drop netty 4.2.12's own bundled config. This "older repo metadata applied over a newer jar" version-mismatch behavior doesn't appear to be documented — and is the part that made this hard to predict.