ClassNotFoundException in Native Mode: Quarkus GraalVM Reachability Metadata Boundaries

Answer

The patterns that evade Quarkus‑provided GraalVM reachability metadata are those where the resource name supplied to ClassLoader.getResource or getResourceAsStream is not a compile‑time constant.

Confirmed facts (from research)

• Quarkus automatically adds the GraalVM reachability metadata repository for known extensions, but it cannot analyse resource names that are built at runtime (e.g., via string concatenation, @ConfigProperty, method arguments, or expression language).
• Typical evasive patterns include:
• Thread.currentThread().getContextClassLoader().getResource(name) where name comes from a property placeholder or config value.
• ClassLoader.getResourceAsStream("META-INF/services/" + serviceInterface) used by ServiceLoader‑style discovery.
• Any lookup where the resource path is assembled from multiple parts that are not known until the application runs.
• Running the application in JVM mode with the GraalVM native‑image agent (-agentlib:native-image-agent=config-output-dir=…) records every class, method and resource actually accessed; the generated reflect-config.json reveals the missing entries.
• When both the automatic repository and application‑level configuration (e.g., @RegisterForReflection or src/main/resources/META-INF/native-image/reflect.json) define the same target, Quarkus merges them; application‑level entries take precedence and override accessibility flags.

Steps to resolve the ClassNotFoundException

1. Enable the native‑image agent in dev mode:

./mvnw quarkus:dev -Dquarkus.native-agent=true

2. Exercise all code paths that load resources (run integration tests or manual requests).
3. Locate the generated reflect-config.json in the agent output directory.
4. Compare it with the existing metadata under target/classes/META-INF/native-image/; any missing resource‑related entries indicate the evasive pattern.
5. Add the missing entries either as @RegisterForReflection on a Quarkus bean or as a custom reflect.json file.
6. Rebuild the native image (./mvnw package -Pnative) and verify that the exception no longer appears.

Missing diagnostic detail

If you cannot reproduce the resource‑loading code path in dev mode, please confirm whether the problematic lookup occurs only during a specific startup bean (e.g., a @Singleton initializer) or only after a particular HTTP endpoint is invoked. Knowing the exact invocation context changes whether the agent must be attached to the test suite or to the running application.