How does Quarkus support GraalVM substitutions for native compilation issues?

A substitution is a mechanism GraalVM provides for swapping out a piece of a class's implementation specifically for the native-image build, used when some existing code does something the static AOT compiler can't safely analyze or support — certain JNI calls, OS-specific behavior, or code relying on dynamic class loading GraalVM can't resolve ahead of time.

@TargetClass(SomeProblematicClass.class)
final class SomeProblematicClass_Substitution {
    @Substitute
    public void problematicMethod() {
        // Native-image-safe replacement implementation
    }
}

Using @TargetClass and @Substitute, a substitution class tells GraalVM's compiler "when you encounter this method during native-image analysis, use this replacement implementation instead of the original," effectively patching third-party or JDK code without modifying the original source, which is invaluable when the problematic code lives in a dependency you don't control.

Quarkus extensions ship substitutions of their own for known problematic library code paths, which is another reason using a proper Quarkus extension for a given library tends to "just work" under native-image compilation, while depending on the same library directly without an extension often surfaces obscure build failures the extension's substitutions would otherwise have silently resolved.