/building-native-image

name: building-native-image
description: Build and troubleshoot GraalVM Native Image applications. Use this skill to build Java applications with GraalVM Native Image, configure CLI options, or resolve build or runtime issues.

​# Building Native Image

Prerequisites

• Set `JAVA_HOME` to a GraalVM distribution if your Java program uses the Native Image SDK. If you do not know the path, ask the user to provide it.

​

Build and Run

1. Compile your Java file with `javac`. 2. Build the Native Image:

	$JAVA_HOME/bin/native-image <app-name>

3. Run the resulting executable:

	./app-name

4. If Native Image cannot find your class file, set the classpath explicitly with the `-cp` option. ​

Troubleshooting

Reachability Metadata

If you encounter runtime errors related to reflection, JNI, resources, serialization, or dynamic proxies, consult [`references/reachability-metadata.md`](references/reachability-metadata.md) before attempting a fix. Use this reference for:

• `NoClassDefFoundError` or `MissingReflectionRegistrationError`
• `MissingJNIRegistrationError`
• `MissingResourceException` (missing resource bundle)
• Any user question about reflection, JNI, proxies, resources, resource bundles, or serialization in Native Image.

​

Native Image Options

To configure classpath, optimization level, output name, platform target, monitoring, or other CLI flags, see [`references/native-image-options.md`](references/native-image-options.md).

Reference Files

| Topic | File | |-------|------| | Native Image CLI options | [references/native-image-options.md](references/native-image-options.md) | | Missing reachability metadata | [references/reachability-metadata.md](references/reachability-metadata.md) |