# Code Cache Segments > The JDK 17-25 segmented code cache, GC-driven unloading, fragmentation, segment sizing, and jcmd Compiler.codecache/CodeHeap_Analytics. Use when aggregate usage looks healthy but one CodeHeap is exhausted, compilation stops or restarts, GC logs show a CodeCache cause, startup rejects manual heap sizes, an OutOfMemoryError reports "Out of space in CodeCache", or a long-running service degrades while aggregate free space remains. Covers runtime-shape discovery so tools do not assume exactly three heaps on every mode or release. Excludes the introductory exhaustion signature (jit-compilation), container memory budgeting (jvm-memory-regions), and Metaspace internals (metaspace-internals). - Skill: `robsonkades/code-cache-segments` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add robsonkades/code-cache-segments` - Raw SKILL.md: https://api.skillmd.com/api/skills/robsonkades/code-cache-segments/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: robsonkades (https://skillmd.com/u/robsonkades) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/robsonkades/code-cache-segments --- # Code Cache Segments ## Purpose On JDK 17-25, treat the normally segmented code cache as three independent allocators with separate ceilings. One `CodeHeap` can sit at 99.8% while the consolidated number reads 72%, and every tool that stops at the consolidated line reports a healthy system. Since JDK 20 the consequence of one full heap is not "the compiler stops": the allocator falls back to the other nmethod heap, so short-lived tier-3 code starts landing in the heap that was reserved for long-lived C2 code, and the GC-driven unloading that replaced the sweeper keys off the **aggregate** free ratio and does not notice. Compilation stops only when the allocation cannot be satisfied after the applicable fallback. Do not hard-code a count of three into tooling: unsegmented and interpreter-only modes have fewer heaps, and later HotSpot builds can add heap kinds. Discover the runtime shape from `Compiler.codecache` and `jdk.CodeCacheConfiguration`. The second failure this prevents is the reflexive "double `ReservedCodeCacheSize`". It works when the pressured segment happens to be one of the two that split the remainder 50/50, and wastes half the increase when it is not — or when the real cost was the GC pauses the code cache was triggering, which a bigger cache also fixes, for a different reason. ## Workflow Before collecting evidence, pin vendor/update, architecture, collector, compiler mode and effective startup flags from the deployed runtime and its CI/image configuration. The command baseline below is HotSpot JDK 25; JDK 17-19 retain the sweeper and need their own lifecycle interpretation. Do not upgrade Java or change the collector to match this skill. If attach, JFR or source access is unavailable, state the gap and keep the diagnosis conditional. 1. **Read every available heap line** from `jcmd Compiler.codecache`, never the consolidated `CodeCache:` line alone. Also read the last line: `Compilation: enabled` or `disabled (not enough contiguous free space left)`, with `stopped_count` and `restarted_count`. 2. **Confirm the runtime shape.** On JDK 17-25, three named heaps is the normal tiered shape; one unnamed heap means segmentation is off. HotSpot enables it ergonomically only with tiered compilation and `ReservedCodeCacheSize` **≥ 240 MB**, so a smaller explicit value de-segments unless `-XX:+SegmentedCodeCache` is also given. Interpreter-only and non-tiered modes legitimately expose fewer heaps. 3. **Read the GC log for the code cache's own causes** — `CodeCache GC Threshold` and `CodeCache GC Aggressive`. On JDK 20+ the code cache is a GC trigger, and under Serial or Parallel each trigger is a **Full GC**. See `references/unloading-and-gc.md`. 4. **Sample at three points, 30-60 seconds apart**, to tell stable exhaustion from oscillating thrashing. Record `jstat -compiler` — `Compiled`, `Failed`, `Invalid` — as part of the incident baseline. 5. **Predict the pressured segment from the tier mix** before measuring: tiers 2 and 3 go to `profiled`, tiers 1 and 4 and native wrappers go to `non-profiled`. Cross-reference `PrintCompilation` or `jdk.Compilation`, and cross-reference deoptimisation events when `non-profiled` is under pressure. 6. **Choose between raising the total and rebalancing** from the measured asymmetry, not from the symptom. Both segments high means total capacity; one pinned at 100% while the other climbs means the split. See `references/segments-and-sizing.md`. 7. **Check the arithmetic before applying manual segment sizes.** On JDK 25, with all segment sizes and `ReservedCodeCacheSize` explicitly set, the enabled heaps must sum to the reserved total after alignment. With only a partial configuration HotSpot computes the unset remainder; without an explicit reserved total it can adjust the total. Recheck this version-sensitive startup logic on the exact runtime. 8. **Validate under the same load that caused the incident**: adequate headroom for the observed growth and deployment/warm-up envelope, an acceptable rate and cost of code-cache-triggered collections, and `Compilation:` enabled across a sustained window. Derive thresholds from the service SLO and restart horizon; 80% is not a universal limit. ## Rules - Monitor per `CodeHeap`, not as a sum. Micrometer and JMX already break the series out by `id` (`CodeHeap 'profiled nmethods'` and the rest); the fault is a dashboard adding them back together. - `profiled nmethods` holds tiers **2 and 3** only. Tier 1 — C1 without profiling — goes to `non-profiled` alongside tier 4 and native wrappers. A trivial method can go straight to `non-profiled` without ever passing through `profiled`. - With default segment sizes, the two nmethod heaps divide the remainder approximately **50/50**, with alignment remainder assigned by startup ergonomics. `non-nmethods` is 5 MB plus one compiler buffer per compiler thread, so it shrinks on a small CPU quota. - A full heap spills into the next one — `non-nmethods → non-profiled → profiled → non-profiled` (`CodeCache::allocate`, `codeCache.cpp`). `CodeHeap '' is full` and the JFR `jdk.CodeCacheFull` event fire only when the fallback failed too. - `NonNMethodCodeHeapSize`, `ProfiledCodeHeapSize` and `NonProfiledCodeHeapSize` are ordinary product flags introduced by JEP 197. Material that wraps them in `-XX:+UnlockDiagnosticVMOptions` is out of date. - `-XX:CodeCacheMinimumFreeSpace` does not exist. The real name is `-XX:CodeCacheMinimumUseSpace`, and it is `develop`-only — unavailable in production builds. - `jstat -compiler` reports **`Failed`**, fed by `sun.ci.totalBailouts`; inspect the actual failure reason before excluding code-cache pressure. Temporary compiler buffers can consume code-cache space even if no nmethod is installed, and older/lower-tier code may still run. `FailedType` is compilation kind, not tier; `Invalid` is not a runtime deoptimization counter. - Declare `-XX:+SegmentedCodeCache` explicitly whenever per-segment visibility matters. Any `ReservedCodeCacheSize` below 240 MB — the common container setting — silently loses it. - There is no sweeper thread and no `zombie` state since JDK 20 (JDK-8290025). A `not_entrant` nmethod is unloaded by the **GC** once no frame references it, so reclaiming code cache costs a GC cycle, and code cache pressure schedules one. - `-XX:+UseCodeCacheFlushing` (the default) now gates the cold-code heuristic and the compiler _restart_ after a full heap; with it off a full heap disables the compiler until restart. Keep it on in production. - JDK 25 CodeHeaps reclaim and coalesce free blocks but do not relocate live nmethods to compact a heap. Relocation would have to preserve active frames, call sites, metadata and runtime references; do not extrapolate this implementation fact into a claim that a future JVM can never compact code. - `jcmd Compiler.codecache` reports aggregate `free` and never the largest contiguous free block. `jcmd Compiler.CodeHeap_Analytics` does — run `aggregate`, then `FreeSpace`. - Fragmentation grows with allocate/free/reallocate cycles, not with raw volume. Frequent deoptimisation and ClassLoader churn are the factories; a heap that only ever fills does not fragment. - The `non-nmethods` heap fails differently: `java.lang.OutOfMemoryError: Out of space in CodeCache for adapters` (or `for method handle intrinsic`) thrown in an application thread at class link time, not a compiler warning. - A restart clears fragmentation and discards all accumulated warm-up. It is a legitimate named mitigation for ClassLoader-churn fragmentation, never a reflex for any code cache symptom. - On JDK 25, `ReservedCodeCacheSize` reserves virtual address space (hard cap 2048 MB), while pages are committed as heaps expand in `CodeCacheExpansionSize` increments (64 KB on the tested build). Committed can exceed live `used`, and resident memory is a separate OS measure. Compare NMT `Code`, `Compiler.codecache`, and process/container RSS instead of treating reservation, commitment and residency as interchangeable. Deliver timestamped per-heap observations, compiler state/counter deltas, the proposed cause and its confirming/falsifying evidence. State expected effects and a load/GC validation bound for any sizing change; neither high utilization nor a restart proves fragmentation. ## References The detailed references use JDK 25 as their executable baseline. Revalidate flags, heap kinds, event fields and startup arithmetic on another feature release or JVM implementation. - [Segments, sizing and rebalancing](references/segments-and-sizing.md) — what each segment holds, the ergonomic defaults and where they come from, the tier-to-CodeHeap mapping, the allocation fallback, the arithmetic a manual configuration must satisfy (and when the JVM fixes it for you), and the decision matrix for raising the total versus changing the split. Read before changing any code cache flag. - [Unloading and the GC](references/unloading-and-gc.md) — what JDK-8290025 removed and what replaced it: the two GC triggers, the cold-code heuristic, the per-collector cost of a `CodeCache GC Threshold` pause, the compiler stop/restart path, and what every surviving `Sweep*` flag means now. Read when the GC log names the code cache, or before touching `UseCodeCacheFlushing` or `NmethodSweepActivity`. - [Diagnosing per-segment exhaustion](references/diagnosing-exhaustion.md) — the `Compiler.codecache` output read line by line, the symptom-to-cause table, `Compiler.CodeHeap_Analytics`, `jstat -compiler` columns, the logging and JFR events, the per-CodeHeap metric series, the adapter `OutOfMemoryError`, and how internal and external fragmentation differ. Read when triaging a live code cache symptom.