Memory Calculator Ignores BPL_JVM_HEAD_ROOM Environment Variable - Uses BPL_JVM_HEADROOM Instead

[dawidworobiec]

The Paketo Azul Zulu buildpack recognizes during build time (visible in logs) but the memory calculator ignores it at runtime, always showing Headroom: 0%. The workaround is to use instead, suggesting the runtime memory calculator expects BPL_JVM_HEADROOM (without the underscore before "ROOM"). This inconsistency between build-time configuration and runtime behavior prevents proper JVM memory headroom allocation. BPL_JVM_HEAD_ROOM``BPE_OVERRIDE_BPL_JVM_HEADROOM

Expected Behavior

Memory Calculator Ignores BPL_JVM_HEAD_ROOM Environment Variable - Uses BPL_JVM_HEADROOM Instead

Current Behavior

The build logs correctly show that BPL_JVM_HEAD_ROOM=12 is recognized during the build phase:

$BPL_JVM_HEAD_ROOM           12                                                           the headroom in memory calculation

However, at runtime, the memory calculator completely ignores this setting and shows:

Calculating JVM memory based on 10144180K available memory
Calculated JVM Memory Configuration: -XX:MaxDirectMemorySize=10M -Xmx9271873K -XX:MaxMetaspaceSize=360306K -XX:ReservedCodeCacheSize=240M -Xss1M (Total Memory: 10144180K, Thread Count: 250, Loaded Class Count: 61199, Headroom: 0%)

The memory calculator allocates nearly 100% of available memory instead of reserving the configured 12% headroom.

Possible Solution

The Azul Zulu buildpack should handle the environment variable name inconsistency between user configuration and the memory calculator. Suggested approaches:
Option 1: Transform/Map Variables (Recommended) The buildpack should internally map to BPL_JVM_HEADROOM before invoking the memory calculator: BPL_JVM_HEAD_ROOM

Option 2: Support Both Variable Names Update the memory calculator (or buildpack's memory calculation logic) to check for both variable names:

• (documented/current) BPL_JVM_HEAD_ROOM
• BPL_JVM_HEADROOM (what actually works)

Steps to Reproduce

Environment:

• Buildpack: paketobuildpacks/azul-zulu:11.2.3
• Java Version: 24 (JRE)
• Builder: paketobuildpacks/builder-jammy-base:latest

Steps:

1. Configure Spring Boot bootBuildImage task with environment variable BPL_JVM_HEAD_ROOM: "12"
2. Build container image using ./gradlew bootBuildImage
3. Observe build logs show the variable is recognized
4. Run container with sufficient memory allocation
5. Check container startup logs for memory calculator output
6. Notice Headroom: 0% instead of expected Headroom: 12%

Workaround: Adding BPE_OVERRIDE_BPL_JVM_HEADROOM: "12" (note: no underscore before "ROOM") to the environment configuration correctly applies the headroom setting.

Motivations

This issue prevents proper JVM memory management in production environments. Without headroom, applications are more susceptible to OutOfMemoryErrors during memory pressure situations. The discrepancy between documented configuration () and actual runtime behavior creates confusion and requires workarounds that aren't obvious to users. BPL_JVM_HEAD_ROOM
The impact is particularly significant for:

• Production deployments where memory management is critical
• Applications with high memory usage that need buffer space
• Teams following Paketo documentation who expect the documented variables to work correctly

[dmikusa]

Thanks for reaching out.

It looks like we should support both, so I'm a little surprised to see it not working.

https://github.com/paketo-buildpacks/libjvm/blob/main/helper/memory_calculator.go#L63-L78

If you set BPL_JVM_HEADROOM, you should see a message at runtime (i.e. before your app starts) that says WARNING: BPL_JVM_HEADROOM is deprecated and will be removed, please switch to BPL_JVM_HEAD_ROOM. BPL_JVM_HEAD_ROOM is intended to be the option going forward.

If you put both, do you see the warning WARNING: You have set both BPL_JVM_HEAD_ROOM and BPL_JVM_HEADROOM. BPL_JVM_HEADROOM has been deprecated, so it will be ignored.?

[dawidworobiec]

We have set both now (just to make sure it persists once fixed / changed) and we receive first warning

WARNING: BPL_JVM_HEADROOM is deprecated and will be removed, please switch to BPL_JVM_HEAD_ROOM.

[dmikusa]

OK, thanks for confirming. Looks like a bug. We'll have to investigate why it's not picking up the other value.