Java Memory Leaks Explained: Causes, Detection and Prevention

import java.util.ArrayList;
import java.util.List;

/**
 * Demonstrates the difference between an object being logically
 * 'done' and being GC-eligible. Run with -Xmx64m to see OOM fast.
 */
public class ReachabilityDemo {

    // Static field == GC root. Anything added here NEVER gets collected.
    private static final List<byte[]> CACHE = new ArrayList<>();

    public static void main(String[] args) throws InterruptedException {
        System.out.println("Simulating a static-field memory leak...");

        for (int iteration = 0; iteration < 1000; iteration++) {
            // Each byte array is 1 MB. We add it and 'forget' about it
            // logically, but CACHE still holds a reference.
            byte[] oneMegabyte = new byte[1024 * 1024];
            CACHE.add(oneMegabyte); // <-- this line is the leak

            System.out.printf(
                "Iteration %d | CACHE size: %d entries | Heap used: %d MB%n",
                iteration,
                CACHE.size(),
                (Runtime.getRuntime().totalMemory()
                    - Runtime.getRuntime().freeMemory()) / (1024 * 1024)
            );

            Thread.sleep(50); // slow it down so you can watch heap grow
        }
    }
}

import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.TimeUnit;

/**
 * Demonstrates a ThreadLocal memory leak inside a thread pool.
 * The thread pool reuses threads, so ThreadLocal values set in one
 * task are still present when the next task runs on the same thread.
 *
 * Run and notice memory climbing. Uncomment the finally block to fix it.
 */
public class ThreadLocalLeakDemo {

    // ThreadLocal holds a large payload to make the leak obvious
    private static final ThreadLocal<byte[]> REQUEST_CONTEXT =
        new ThreadLocal<>();

    public static void main(String[] args) throws InterruptedException {
        // A fixed thread pool — threads never die, so ThreadLocals accumulate
        ExecutorService threadPool = Executors.newFixedThreadPool(4);

        for (int taskNumber = 0; taskNumber < 500; taskNumber++) {
            final int currentTask = taskNumber;

            threadPool.submit(() -> {
                try {
                    // Simulating per-request data (e.g., user session, trace ID)
                    // Each 'request' stores 500 KB of data in ThreadLocal
                    byte[] requestPayload = new byte[500 * 1024];
                    requestPayload[0] = (byte) currentTask; // use it slightly
                    REQUEST_CONTEXT.set(requestPayload);

                    // ... do the actual work ...
                    processRequest(currentTask);

                    // BUG: we return here without cleaning up.
                    // The thread goes back to the pool, ThreadLocal value stays.

                } finally {
                    // FIX: always call remove() in a finally block.
                    // Uncomment the line below to prevent the leak:
                    // REQUEST_CONTEXT.remove();
                }
            });

            if (currentTask % 50 == 0) {
                long usedHeapMB = (Runtime.getRuntime().totalMemory()
                    - Runtime.getRuntime().freeMemory()) / (1024 * 1024);
                System.out.printf(
                    "Submitted %d tasks | Heap used: ~%d MB%n",
                    currentTask, usedHeapMB
                );
            }
        }

        threadPool.shutdown();
        threadPool.awaitTermination(30, TimeUnit.SECONDS);
    }

    private static void processRequest(int taskNumber) {
        // Simulate work — read the ThreadLocal value
        byte[] context = REQUEST_CONTEXT.get();
        // In real code this might be a user object, DB connection wrapper, etc.
        System.out.printf("Task %d processed on thread: %s%n",
            taskNumber, Thread.currentThread().getName());
    }
}

import java.lang.ref.SoftReference;
import java.lang.ref.WeakReference;
import java.util.WeakHashMap;

/**
 * Side-by-side comparison of Strong, Soft, and Weak references.
 * Also shows WeakHashMap auto-eviction in action.
 *
 * Run with: java -Xmx32m ReferenceTypesDemo
 */
public class ReferenceTypesDemo {

    public static void main(String[] args) throws InterruptedException {
        demonstrateSoftReference();
        demonstrateWeakHashMap();
    }

    private static void demonstrateSoftReference() {
        System.out.println("=== SoftReference Demo ===");

        // Create a large object and wrap it in a SoftReference
        byte[] largeDataBlob = new byte[10 * 1024 * 1024]; // 10 MB
        SoftReference<byte[]> softCache = new SoftReference<>(largeDataBlob);

        // Drop the strong reference — now only the soft ref holds it
        largeDataBlob = null;

        byte[] retrieved = softCache.get();
        System.out.println("Before memory pressure — data available: "
            + (retrieved != null)); // true: GC hasn't collected it yet

        // Simulate memory pressure by allocating a lot
        try {
            byte[] memoryHog = new byte[25 * 1024 * 1024]; // forces GC
            System.out.println("Allocated pressure block: " + memoryHog.length);
        } catch (OutOfMemoryError oomError) {
            // JVM clears soft refs before throwing OOM
            System.out.println("OOM triggered — soft refs were cleared first");
        }

        // After pressure, soft reference MAY have been cleared
        byte[] afterPressure = softCache.get();
        System.out.println("After memory pressure — data available: "
            + (afterPressure != null)); // likely null now
    }

    private static void demonstrateWeakHashMap() throws InterruptedException {
        System.out.println("\n=== WeakHashMap Auto-Eviction Demo ===");

        WeakHashMap<String, String> metadataCache = new WeakHashMap<>();

        // IMPORTANT: string literals are interned — they always have a
        // strong reference from the string pool. Use 'new String()' to
        // create a key with no other strong references.
        String sessionKey = new String("user-session-abc123");
        metadataCache.put(sessionKey, "{ role: admin, locale: en-US }");

        System.out.println("Cache size before GC: " + metadataCache.size()); // 1

        // Drop the only strong reference to the key
        sessionKey = null;

        // Suggest GC — not guaranteed, but usually runs in demo context
        System.gc();
        Thread.sleep(200); // give GC time to run

        // WeakHashMap automatically removes entries whose keys were collected
        System.out.println("Cache size after GC:   " + metadataCache.size()); // 0
        System.out.println("Entry auto-evicted — no manual cleanup needed!");
    }
}

/**
 * This file isn't 'runnable' in the traditional sense — it documents
 * the exact JVM flags and jcmd commands you need for production leak detection.
 *
 * Add these flags to your JVM startup command (e.g., in your Dockerfile,
 * systemd unit, or Kubernetes deployment's JAVA_OPTS):
 *
 * RECOMMENDED JVM FLAGS FOR PRODUCTION LEAK DETECTION:
 * =====================================================
 *
 * 1. Automatic heap dump on OutOfMemoryError:
 *    -XX:+HeapDumpOnOutOfMemoryError
 *    -XX:HeapDumpPath=/var/log/myapp/heapdumps/
 *
 * 2. GC logging (JDK 9+ unified logging syntax):
 *    -Xlog:gc*:file=/var/log/myapp/gc.log:time,uptime:filecount=5,filesize=20m
 *
 * 3. Native memory tracking (for off-heap / metaspace leaks):
 *    -XX:NativeMemoryTracking=summary
 *
 * 4. GC algorithm choice — G1 is default in JDK 9+, good for most workloads:
 *    -XX:+UseG1GC
 *    -XX:MaxGCPauseMillis=200
 *
 * LIVE COMMANDS AGAINST A RUNNING JVM:
 * =====================================
 *
 * # Find the PID of your Java process:
 * $ jps -l
 * 18423 com.example.MyService
 *
 * # Trigger a heap dump without killing the process:
 * $ jcmd 18423 GC.heap_dump /tmp/heapdump-$(date +%Y%m%d-%H%M%S).hprof
 *
 * # Print class histogram (top memory consumers by class, no full dump):
 * $ jcmd 18423 GC.class_histogram | head -30
 *
 * # Print native memory summary (catches metaspace and direct buffer leaks):
 * $ jcmd 18423 VM.native_memory summary
 *
 * # Print ThreadLocal info via thread dump (look for long-lived threads
 * # with unexpectedly large thread-local maps):
 * $ jcmd 18423 Thread.print > /tmp/threaddump.txt
 *
 * INTERPRETING A CLASS HISTOGRAM:
 * ================================
 * num  #instances  #bytes  class name
 * ---  ----------  ------  ----------
 *   1:    950,234  22.8MB  [B  (byte arrays)
 *   2:    420,000  13.4MB  com.example.UserSession
 *   3:    420,000   6.7MB  java.util.HashMap$Node
 *
 * If UserSession instance count keeps growing between samples,
 * and UserSession holds a HashMap (hence the Node count mirrors it),
 * you almost certainly have a session / cache that never evicts.
 */
public class LeakDetectionSetup {
    // This class serves as living documentation.
    // In your actual project, put these flags in a 'jvm-flags.md' or
    // your infrastructure-as-code so the team always runs with them.
    public static void main(String[] args) {
        System.out.println("JVM flags documented above. Check your startup scripts.");

        // Print current heap stats at runtime for quick sanity checks:
        Runtime jvmRuntime = Runtime.getRuntime();
        long maxHeapBytes    = jvmRuntime.maxMemory();
        long totalHeapBytes  = jvmRuntime.totalMemory();
        long freeHeapBytes   = jvmRuntime.freeMemory();
        long usedHeapBytes   = totalHeapBytes - freeHeapBytes;

        System.out.printf("Max heap:   %6d MB%n", maxHeapBytes  / (1024 * 1024));
        System.out.printf("Used heap:  %6d MB%n", usedHeapBytes / (1024 * 1024));
        System.out.printf("Free heap:  %6d MB%n", freeHeapBytes / (1024 * 1024));
    }
}