When a Java application is compiled ahead of time into a native binary, some class initialization can run at build time and be snapshotted into the image. What does that buy, and what can go wrong?

## The mechanism In a normal JVM, a class's static initializer runs the first time the class is actively used. That work — parsing configuration, building maps, compiling patterns, allocating constant tables — happens during startup and contributes to the slow first seconds of a large application. A native-image build can instead run those initializers on the build machine. The objects they create become part of the *image heap*: a pre-built object graph written into the executable and made available to the process at startup, typically by mapping it in rather than reconstructing it. The running program finds those data structures already present, fully initialized, with no work performed. This is one of the main reasons a native image starts in milliseconds. It is also why frameworks that do ahead-of-time processing pair so well with it: they move configuration resolution into the build, and build-time initialization then freezes the resolved result into the binary. ## The failure modes Build-time initialization changes *when* code runs and therefore *what environment* it observes. Every problem follows from that. **Entropy is frozen.** A random generator seeded in a static initializer at build time produces the same sequence in every run of the shipped binary on every machine. For a security-relevant generator this is a serious vulnerability, not a quirk. **Build environment leaks into the artifact.** Hostname, current working directory, time zone, locale, environment variables, and the build timestamp are all captured as constants. A value that was meant to reflect the deployment reflects the build agent instead. **Secrets get embedded.** If initialization reads a credential from the build environment or a build-time file, that credential is now bytes inside a binary that gets distributed. This is a supply-chain exposure that is easy to create accidentally. **Native resources cannot be captured.** File descriptors, sockets, threads, loaded native libraries, and memory-mapped regions have no meaning in a different process. The toolchain generally detects these and fails the build, reporting which object reached the image heap and the reference chain that pulled it in — which is annoying but far better than silent corruption. **Initialization order becomes a build-time property.** A class initialized at build time cannot touch a class marked run-time-initialized, because the latter has no state yet. Mixed policies across a dependency produce build errors whose message is about reachability rather than about the underlying policy conflict, and untangling them is the routine cost of adopting this. ## How the choice is expressed and reasoned about Toolchains expose the policy per class or package: initialize at build time, or defer to run time. Library authors annotate or configure their own classes; application authors do the same for their code and occasionally override a library's choice. The default policy has moved over time toward deferring more to run time, precisely because the failure modes above are subtle, with build-time initialization applied where it is provably safe or explicitly requested. The reasoning rule is simple to state: a class may be initialized at build time if its static state is a pure function of the code — deterministic, environment-independent, holding no external resource and no entropy. Lookup tables, immutable constants, compiled patterns over literal strings, and enum-like registries qualify. Anything that reads the clock, the environment, the filesystem, the network, a random source, or a secret does not. ## What to check in review Treat it as a security-relevant configuration. Ask which packages are initialized at build time, and for each, whether any transitively-reached initializer touches entropy, the environment, or secrets. When a build fails because an unsupported object landed in the image heap, read the reference chain rather than reflexively marking classes run-time-initialized until it compiles — that chain is telling you which initializer is doing environment-dependent work, and it is usually the same initializer that would have silently baked in something wrong had it been capturable. ## The one-line summary Build-time initialization trades runtime work for frozen state: it is why startup is nearly free, and it is wrong for anything whose correct value depends on when or where the program runs.