# Building Native Image

> 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.

- Skill: `oracle/building-native-image` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add oracle/building-native-image`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oracle/building-native-image/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Oracle (https://skillmd.com/u/oracle)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/oracle/building-native-image

---


​# 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:
	```bash
	$JAVA_HOME/bin/native-image <app-name>
	```
3. Run the resulting executable:
	```bash
	./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) |