The -H:+CompatibilityMode for Native Image

The goal of this mode is to remove native-image implementation-specific behavior: no build-time initialization on classpath, no custom system properties for native image, no substitutions on classpath, no user features, future defaults enabled by default.

It still does not modify the key restrictions of Native Image which are related to dynamic access and run-time class loading.

Also, this mode still does not disable flags such as --features and --initialize-at-build-time from the command line. This will be discussed separately and done in a separate PR.

To get the same behavior as the underlying language it is recommended to use this flag with:

  native-image -H:+CompatibilityMode -H:Preserve=all -H:+RuntimeClassLoading App

And to run it with:

  ./app -Djava.home=<path-to-java-home> -Djava.class.path=<cp> -Djdk.module.path=<module-path>

Author: vjovanov

.github/workflows/micronaut-compatibility-preserve-crema.yml

@@ -0,0 +1,56 @@
+#
+# Copyright (c) 2026, 2026, Oracle and/or its affiliates. All rights reserved.
+# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+#
+# The Universal Permissive License (UPL), Version 1.0
+#
+# Subject to the condition set forth below, permission is hereby granted to any
+# person obtaining a copy of this software, associated documentation and/or
+# data (collectively the "Software"), free of charge and under any and all
+# copyright rights in the Software, and any and all patent rights owned or
+# freely licensable by each licensor hereunder covering either (i) the
+# unmodified Software as contributed to or provided by such licensor, or (ii)
+# the Larger Works (as defined below), to deal in both
+#
+# (a) the Software, and
+#
+# (b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
+# one is included with the Software each a "Larger Work" to which the Software
+# is contributed by such licensors),
+#
+# without restriction, including without limitation the rights to copy, create
+# derivative works of, display, perform, and distribute the Software and make,
+# use, sell, offer for sale, import, export, have made, and have sold the
+# Software and the Larger Work(s), and to sublicense the foregoing rights on
+# either these or other terms.
+#
+# This license is subject to the following condition:
+#
+# The above copyright notice and either this complete permission notice or at a
+# minimum a reference to the UPL must be included in all copies or substantial
+# portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+#
+name: Weekly Micronaut Tests (-H:+CompatibilityMode -H:Preserve=all -H:+RuntimeClassLoading)
+
+on:
+  pull_request:
+    paths:
+      - '.github/workflows/micronaut-template.yml'
+      - '.github/workflows/micronaut-compatibility-preserve.yml'
+  schedule:
+  - cron: '0 2 * * 1'
+  workflow_dispatch:
+
+jobs:
+  call-template:
+    uses: './.github/workflows/micronaut-template.yml'
+    with:
+      NATIVE_IMAGE_OPTIONS: '-H:+UnlockExperimentalVMOptions -H:+ReportExceptionStackTraces -H:+CompatibilityMode -H:Preserve=all -H:+RuntimeClassLoading -H:-UnlockExperimentalVMOptions'

.github/workflows/micronaut-template.yml

@@ -52,7 +52,6 @@ env:
   MICRONAUT_JAVA_VERSION: 21
   # Enforce experimental option checking in CI (GR-47922)
   NATIVE_IMAGE_EXPERIMENTAL_OPTIONS_ARE_FATAL: 'true'
-  NATIVE_IMAGE_OPTIONS: ${{ inputs.NATIVE_IMAGE_OPTIONS }}
 
 permissions:
   contents: read # to fetch code (actions/checkout)
@@ -69,7 +68,9 @@ jobs:
       uses: ./.github/actions/build-graalvm
       with:
         java-version: ${{ env.MICRONAUT_JAVA_VERSION }}
-    - name: Run nativeTest in Micronaut launch project
+    - name: Run nativeTest in Micronaut launch project${{ inputs.NATIVE_IMAGE_OPTIONS && format(' with ''{0}''', inputs.NATIVE_IMAGE_OPTIONS) || '' }}
+      env:
+        NATIVE_IMAGE_OPTIONS: ${{ inputs.NATIVE_IMAGE_OPTIONS }}
       run: |
         curl --fail --silent --location --retry 3 --max-time 10 --output demo.zip --request GET 'https://launch.micronaut.io/create/default/com.example.demo?lang=JAVA&build=GRADLE&test=JUNIT&javaVersion=JDK_${{ env.MICRONAUT_JAVA_VERSION }}'
         unzip demo.zip
@@ -81,6 +82,8 @@ jobs:
         repository: micronaut-projects/micronaut-core
         path: ${{ env.MICRONAUT_CORE_PATH }}
     - name: Run nativeTest in micronaut-core${{ inputs.NATIVE_IMAGE_OPTIONS && format(' with ''{0}''', inputs.NATIVE_IMAGE_OPTIONS) || '' }}
+      env:
+        NATIVE_IMAGE_OPTIONS: ${{ inputs.NATIVE_IMAGE_OPTIONS }}
       run: |
         cd ${{ env.MICRONAUT_CORE_PATH }}
         ./gradlew nativeTest

.github/workflows/reachability-metadata-compatibility-preserve-crema.yml

@@ -0,0 +1,56 @@
+#
+# Copyright (c) 2026, 2026, Oracle and/or its affiliates. All rights reserved.
+# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+#
+# The Universal Permissive License (UPL), Version 1.0
+#
+# Subject to the condition set forth below, permission is hereby granted to any
+# person obtaining a copy of this software, associated documentation and/or
+# data (collectively the "Software"), free of charge and under any and all
+# copyright rights in the Software, and any and all patent rights owned or
+# freely licensable by each licensor hereunder covering either (i) the
+# unmodified Software as contributed to or provided by such licensor, or (ii)
+# the Larger Works (as defined below), to deal in both
+#
+# (a) the Software, and
+#
+# (b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
+# one is included with the Software each a "Larger Work" to which the Software
+# is contributed by such licensors),
+#
+# without restriction, including without limitation the rights to copy, create
+# derivative works of, display, perform, and distribute the Software and make,
+# use, sell, offer for sale, import, export, have made, and have sold the
+# Software and the Larger Work(s), and to sublicense the foregoing rights on
+# either these or other terms.
+#
+# This license is subject to the following condition:
+#
+# The above copyright notice and either this complete permission notice or at a
+# minimum a reference to the UPL must be included in all copies or substantial
+# portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+#
+name: Weekly Reachability Metadata Tests (-H:+CompatibilityMode -H:Preserve=all -H:+RuntimeClassLoading)
+
+on:
+  pull_request:
+    paths:
+      - '.github/workflows/reachability-metadata-template.yml'
+      - '.github/workflows/reachability-metadata-compatibility-preserve.yml'
+  schedule:
+  - cron: '0 1 * * 1'
+  workflow_dispatch:
+
+jobs:
+  call-template:
+    uses: './.github/workflows/reachability-metadata-template.yml'
+    with:
+      NATIVE_IMAGE_OPTIONS: '-H:+UnlockExperimentalVMOptions -H:+ReportExceptionStackTraces -H:+CompatibilityMode -H:Preserve=all -H:+RuntimeClassLoading -H:-UnlockExperimentalVMOptions'

docs/reference-manual/native-image/guides/troubleshoot-run-time-errors.md

@@ -41,10 +41,20 @@ For diagnosing shared libraries built with Native Image, you can either:
 * specify `-R:MissingRegistrationReportingMode=Exit` when building a native shared library;
 * or specify `-XX:MissingRegistrationReportingMode=Exit` when the isolate is created. `graal_create_isolate_params_t` has `argc` and `argv` fields that can be used to pass C-style command-line options at run time.
 
-### 2. Set java.home Explicitly
+### 2. Set java.home and Classpath Explicitly
 
 If your application code uses the `java.home` property, set it explicitly with `-Djava.home=<path>` when running a native executable.
-Otherwise, the `System.getProperty("java.home")` call will return a `null` value.
+Otherwise, the `System.getProperty("java.home")` call will return a `null` value. For instance, you can run your native executable like this:
+
+```console
+./my-native-app -Djava.home=/path/to/jdk
+```
+
+Some applications also need access to the classpath and module path at run time. Those can be set with `-Djava.class.path=<class-path>` and `-Djdk.module.path=<module-path>` when running the executable. Here's how you would specify both properties:
+
+```console
+./my-native-app -Djava.class.path=/path/to/classes:/path/to/lib.jar -Djdk.module.path=/path/to/modules
+```
 
 ### 3. Enable URL Protocols
 

sdk/src/org.graalvm.nativeimage/src/org/graalvm/nativeimage/ImageInfo.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, 2025, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2018, 2026, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * The Universal Permissive License (UPL), Version 1.0
@@ -161,7 +161,7 @@ public static boolean inImageBuildtimeCode() {
      */
     public static boolean isExecutable() {
         ensureKindAvailable();
-        return PROPERTY_IMAGE_KIND_VALUE_EXECUTABLE.equals(System.getProperty(PROPERTY_IMAGE_KIND_KEY));
+        return PROPERTY_IMAGE_KIND_VALUE_EXECUTABLE.equals(ImageKindHolder.IMAGE_KIND);
     }
 
     /**
@@ -171,13 +171,21 @@ public static boolean isExecutable() {
      */
     public static boolean isSharedLibrary() {
         ensureKindAvailable();
-        return PROPERTY_IMAGE_KIND_VALUE_SHARED_LIBRARY.equals(System.getProperty(PROPERTY_IMAGE_KIND_KEY));
+        return PROPERTY_IMAGE_KIND_VALUE_SHARED_LIBRARY.equals(ImageKindHolder.IMAGE_KIND);
     }
 
     private static void ensureKindAvailable() {
-        if (inImageCode() && System.getProperty(PROPERTY_IMAGE_KIND_KEY) == null) {
+        if (inImageCode() && ImageKindHolder.IMAGE_KIND == null) {
             throw new UnsupportedOperationException(
                             "The kind of image that is built (executable or shared library) is not available yet because the relevant command line option has not been parsed yet.");
         }
     }
+
+    /// This class is needed so [#IMAGE_KIND] does not get initialized before the
+    /// [#PROPERTY_IMAGE_KIND_KEY] property is set.
+    /// [ImageInfo] is initialized very early in the build process before the
+    /// [#PROPERTY_IMAGE_KIND_KEY] property is set by the image builder.
+    private static final class ImageKindHolder {
+        static final String IMAGE_KIND = System.getProperty(PROPERTY_IMAGE_KIND_KEY);
+    }
 }

substratevm/CHANGELOG.md

@@ -24,6 +24,7 @@ This changelog summarizes major changes to GraalVM Native Image.
 * (GR-63737) Deprecated API function `Threading.registerRecurringCallback(...)` without replacement. This method should not be used as it is inherently unsafe.
 * (GR-63737) Removed deprecated API function `ProcessPropertiesSupport.setLocale(...)`.
 * (GR-52538) (GR-69523) (GR-73129) Introduce new SerialGC policy `Adaptive2` and default to mark-compact collection in the old generation. On average, this reduces memory usage and often improves throughput and latency. Restore the old behavior with: `-H:-CompactingOldGen -H:InitialCollectionPolicy=Adaptive`.
+* (GR-71974) Introduced `-H:+CompatibilityMode` that disables all Native Image features that allow users to diverge from original program semantics: build-time initialization for classpath classes, native-image-specific system properties, substitutions on the classpath, and user features, while enabling all future defaults. This mode does not modify key Native Image restrictions related to dynamic access (reachability metadata) and run-time class loading as those are accepted limitations of native image.
 
 ## GraalVM 25
 * (GR-52276) (GR-61959) Add support for Arena.ofShared().

substratevm/src/com.oracle.svm.core.posix/src/com/oracle/svm/core/posix/PosixSystemPropertiesSupport.java

@@ -26,15 +26,19 @@
 
 import org.graalvm.nativeimage.c.type.CCharPointer;
 import org.graalvm.nativeimage.c.type.CTypeConversion;
+import org.graalvm.word.impl.Word;
 
 import com.oracle.svm.core.graal.stackvalue.UnsafeStackValue;
 import com.oracle.svm.core.jdk.SystemPropertiesSupport;
 import com.oracle.svm.core.posix.headers.Limits;
 import com.oracle.svm.core.posix.headers.Unistd;
-import org.graalvm.word.impl.Word;
 
 public abstract class PosixSystemPropertiesSupport extends SystemPropertiesSupport {
 
+    public PosixSystemPropertiesSupport(boolean compatibilityMode) {
+        super(compatibilityMode);
+    }
+
     @Override
     protected String jvmLibName() {
         return "libjvm" + jvmLibSuffix();

substratevm/src/com.oracle.svm.core.posix/src/com/oracle/svm/core/posix/darwin/DarwinSystemPropertiesSupport.java

@@ -24,6 +24,7 @@
  */
 package com.oracle.svm.core.posix.darwin;
 
+import com.oracle.svm.hosted.NativeImageOptions;
 import org.graalvm.nativeimage.ImageSingletons;
 import org.graalvm.nativeimage.Platform;
 import org.graalvm.nativeimage.c.function.CLibrary;
@@ -32,6 +33,7 @@
 import org.graalvm.nativeimage.c.type.CTypeConversion.CCharPointerHolder;
 import org.graalvm.nativeimage.impl.RuntimeSystemPropertiesSupport;
 import org.graalvm.word.UnsignedWord;
+import org.graalvm.word.impl.Word;
 
 import com.oracle.svm.core.feature.AutomaticallyRegisteredFeature;
 import com.oracle.svm.core.feature.InternalFeature;
@@ -43,17 +45,20 @@
 import com.oracle.svm.core.posix.headers.Stdlib;
 import com.oracle.svm.core.posix.headers.Unistd;
 import com.oracle.svm.core.posix.headers.darwin.Foundation;
+import com.oracle.svm.shared.singletons.traits.SingletonTraits;
 import com.oracle.svm.shared.singletons.traits.BuiltinTraits.AllAccess;
 import com.oracle.svm.shared.singletons.traits.BuiltinTraits.BuildtimeAccessOnly;
 import com.oracle.svm.shared.singletons.traits.BuiltinTraits.Disallowed;
 import com.oracle.svm.shared.singletons.traits.BuiltinTraits.NoLayeredCallbacks;
-import com.oracle.svm.shared.singletons.traits.SingletonTraits;
-import org.graalvm.word.impl.Word;
 
 @SingletonTraits(access = AllAccess.class, layeredCallbacks = NoLayeredCallbacks.class, other = Disallowed.class)
 @CLibrary(value = "darwin", requireStatic = true)
 public class DarwinSystemPropertiesSupport extends PosixSystemPropertiesSupport {
 
+    public DarwinSystemPropertiesSupport(boolean compatibilityMode) {
+        super(compatibilityMode);
+    }
+
     @Override
     protected String javaIoTmpdirValue() {
         /* Darwin has a per-user temp dir */
@@ -143,7 +148,8 @@ protected String jvmLibSuffix() {
 class DarwinSystemPropertiesFeature implements InternalFeature {
     @Override
     public void duringSetup(DuringSetupAccess access) {
-        ImageSingletons.add(RuntimeSystemPropertiesSupport.class, new DarwinSystemPropertiesSupport());
+        ImageSingletons.add(RuntimeSystemPropertiesSupport.class,
+                        new DarwinSystemPropertiesSupport(NativeImageOptions.compatibilityMode()));
         ImageSingletons.add(SystemPropertiesSupport.class, (SystemPropertiesSupport) ImageSingletons.lookup(RuntimeSystemPropertiesSupport.class));
     }
 }

substratevm/src/com.oracle.svm.core.posix/src/com/oracle/svm/core/posix/linux/LinuxSystemPropertiesSupport.java

@@ -38,15 +38,20 @@
 import com.oracle.svm.core.posix.PosixSystemPropertiesSupport;
 import com.oracle.svm.core.posix.headers.Stdlib;
 import com.oracle.svm.core.posix.headers.Utsname;
+import com.oracle.svm.hosted.NativeImageOptions;
+import com.oracle.svm.shared.singletons.traits.SingletonTraits;
 import com.oracle.svm.shared.singletons.traits.BuiltinTraits.AllAccess;
 import com.oracle.svm.shared.singletons.traits.BuiltinTraits.BuildtimeAccessOnly;
 import com.oracle.svm.shared.singletons.traits.BuiltinTraits.SingleLayer;
 import com.oracle.svm.shared.singletons.traits.SingletonLayeredInstallationKind.InitialLayerOnly;
-import com.oracle.svm.shared.singletons.traits.SingletonTraits;
 
 @SingletonTraits(access = AllAccess.class, layeredCallbacks = SingleLayer.class, layeredInstallationKind = InitialLayerOnly.class)
 public class LinuxSystemPropertiesSupport extends PosixSystemPropertiesSupport {
 
+    public LinuxSystemPropertiesSupport(boolean compatibilityMode) {
+        super(compatibilityMode);
+    }
+
     @Override
     protected String javaIoTmpdirValue() {
         /*
@@ -110,7 +115,7 @@ public boolean isInConfiguration(IsInConfigurationAccess access) {
 
     @Override
     public void duringSetup(DuringSetupAccess access) {
-        LinuxSystemPropertiesSupport singleton = new LinuxSystemPropertiesSupport();
+        LinuxSystemPropertiesSupport singleton = new LinuxSystemPropertiesSupport(NativeImageOptions.compatibilityMode());
         ImageSingletons.add(RuntimeSystemPropertiesSupport.class, singleton);
         ImageSingletons.add(SystemPropertiesSupport.class, singleton);
     }

substratevm/src/com.oracle.svm.core.windows/src/com/oracle/svm/core/windows/WindowsSystemPropertiesSupport.java

@@ -37,6 +37,7 @@
 import org.graalvm.nativeimage.c.type.WordPointer;
 import org.graalvm.nativeimage.impl.RuntimeSystemPropertiesSupport;
 import org.graalvm.word.UnsignedWord;
+import org.graalvm.word.impl.Word;
 
 import com.oracle.svm.core.c.NonmovableArrays;
 import com.oracle.svm.core.feature.AutomaticallyRegisteredFeature;
@@ -60,7 +61,7 @@
 import com.oracle.svm.core.windows.headers.WinVer;
 import com.oracle.svm.core.windows.headers.WindowsLibC;
 import com.oracle.svm.core.windows.headers.WindowsLibC.WCharPointer;
-import org.graalvm.word.impl.Word;
+import com.oracle.svm.hosted.NativeImageOptions;
 
 @SingletonTraits(access = AllAccess.class, layeredCallbacks = NoLayeredCallbacks.class, other = Disallowed.class)
 public class WindowsSystemPropertiesSupport extends SystemPropertiesSupport {
@@ -74,6 +75,10 @@ public class WindowsSystemPropertiesSupport extends SystemPropertiesSupport {
     private static final int VER_PLATFORM_WIN32_WINDOWS = 1;
     private static final int VER_PLATFORM_WIN32_NT = 2;
 
+    public WindowsSystemPropertiesSupport(boolean compatibilityMode) {
+        super(compatibilityMode);
+    }
+
     @Override
     protected String userNameValue() {
         WCharPointer userName = WindowsLibC._wgetenv(NonmovableArrays.addressOf(NonmovableArrays.fromImageHeap(USERNAME), 0));
@@ -406,7 +411,8 @@ private void computeOsNameAndVersion() {
 class WindowsSystemPropertiesFeature implements InternalFeature {
     @Override
     public void duringSetup(DuringSetupAccess access) {
-        ImageSingletons.add(RuntimeSystemPropertiesSupport.class, new WindowsSystemPropertiesSupport());
+        ImageSingletons.add(RuntimeSystemPropertiesSupport.class,
+                        new WindowsSystemPropertiesSupport(NativeImageOptions.compatibilityMode()));
         ImageSingletons.add(SystemPropertiesSupport.class, (SystemPropertiesSupport) ImageSingletons.lookup(RuntimeSystemPropertiesSupport.class));
     }
 }