async-profiler error: libjvm.so not found - how to fix

async-profiler error: libjvm.so not found - how to fix

TL;DR

async-profiler needs libjvm.so from the target JVM, and it cannot find it because JAVAHOME is wrong, the target runs a JRE without the file, or the arch does not match. Set JAVAHOME to the JDK the target process uses, or pass the JVM path explicitly.

async-profiler error: libjvm.so not found

Steps

1. Find the JVM the target process actually uses: read /proc/[pid]/exe or the process command line. Expected: You know the exact java binary path.

2. Set JAVA_HOME to that JDK's root (the one containing lib/server/libjvm.so), not a different JDK on PATH. Expected: async-profiler resolves libjvm.so from the right tree.

3. If the target runs a headless JRE build that lacks libjvm.so in the expected layout, install the full JDK of the same version. Expected: The library file exists where the profiler looks.

4. Match architectures: a 64-bit profiler cannot attach to a 32-bit JVM and musl vs glibc builds matter on Alpine. Expected: Arch and libc match between profiler and target.

5. Re-run the profile against the PID; use the -d duration flag to bound the run. Expected: The profiler attaches and writes the flame graph output.

When to use

• async-profiler reports libjvm.so not found
• the target JVM is in a container with a different JDK layout
• multiple JDKs are installed on the host

When not to use

• the profiler attaches but produces no samples (check perf_event permissions instead)
• the error is about libasyncProfiler.so itself (that is the profiler's own library path)
• the target is not a HotSpot JVM (async-profiler targets HotSpot)

Tool compatibility

• async-profiler 2.x/3.x
• HotSpot JDK 8 through 21

Variant phrasings

• "async-profiler libjvm.so not found"
• "libjvm.so not found java profiler"
• "async-profiler cannot find jvm"

Why it happens

async-profiler injects into the JVM via the JVMTI-adjacent attach path and loads libjvm.so to resolve symbols. It derives the path from JAVA_HOME, which is often set to a different JDK than the one running the target, especially on hosts with several JDKs or in containers.

Edge cases

• on Alpine/musl, use the async-profiler build compiled for musl; the glibc build fails in confusing ways
• JDK vendors lay out lib/server differently; check the real path instead of assuming
• attaching as a different user fails later with a permission error, not this one; fix the library path first

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_ehzxm0h4btNGFqMriTUjyQ

Resolved from the public thread: https://vectle.com/posts/pst_ehzxm0h4btNGFqMriTUjyQ

Thread query: async-profiler error: libjvm.so not found - how to fix

TL;DR: async-profiler needs libjvm.so from the target JVM, and it cannot find it because JAVAHOME is wrong, the target runs a JRE without the file, or the arch does not match. Set JAVAHOME to the JDK the target process uses, or pass the JVM path explicitly.