alibaba/arthas · error · IllegalStateException

Can not find libasyncProfiler so, please check the arthas di

Error message

Can not find libasyncProfiler so, please check the arthas directory.

What it means

Thrown by profilerInstance() in the `profiler` command when running on Linux or macOS but the async-profiler native library (libasyncProfiler.so / .dylib) cannot be located in the arthas directory (libPath is null) and the action is not an explicit `load` from a custom path. Arthas bundles the native agent for supported platforms; if it is missing the profiler cannot start.

Source

Thrown at core/src/main/java/com/taobao/arthas/core/command/monitor200/ProfilerCommand.java:583

            FileInputStream libInputStream = null;
            try {
                File tmpLibFile = File.createTempFile(VmTool.JNI_LIBRARY_NAME, null);
                tmpLibOutputStream = new FileOutputStream(tmpLibFile);
                libInputStream = new FileInputStream(libPath);

                IOUtils.copy(libInputStream, tmpLibOutputStream);
                libPath = tmpLibFile.getAbsolutePath();
                logger.debug("copy {} to {}", libPath, tmpLibFile);
            } catch (Throwable e) {
                logger.error("try to copy lib error! libPath: {}", libPath, e);
            } finally {
                IOUtils.close(libInputStream);
                IOUtils.close(tmpLibOutputStream);
            }
            profiler = AsyncProfiler.getInstance(libPath);
        } else {
            if (OSUtils.isLinux() || OSUtils.isMac()) {
                throw new IllegalStateException("Can not find libasyncProfiler so, please check the arthas directory.");
            } else {
                throw new IllegalStateException("Current OS do not support AsyncProfiler, Only support Linux/Mac.");
            }
        }

        return profiler;
    }

    /**
     * https://github.com/async-profiler/async-profiler/blob/v4.4/src/arguments.cpp
     */
    public enum ProfilerAction {
        // start, resume, stop, dump, status, meminfo, list,
        start, resume, stop, dump, status, meminfo, list,
        version,

        load,
        execute,

View on GitHub (pinned to 21cf2e9ba5)

Solutions

Reinstall or re-download a full arthas distribution so libasyncProfiler.so (Linux) or .dylib (Mac) is present in the arthas directory.
Use `profiler load /absolute/path/to/libasyncProfiler.so` to point at a manually built/downloaded native lib.
Verify the file exists and is readable in the arthas working directory (ls the directory arthas was launched from).
Ensure the native lib matches your OS/arch (e.g. linux-x64).

Example fix

// before
profiler start
// after
profiler load /opt/async-profiler/build/libasyncProfiler.so
profiler start

Defensive patterns

Strategy: try-catch

Validate before calling

// Detect the native lib before invoking profiler actions
File lib = new File(arthasDir, System.mapLibraryName("asyncProfiler"));
if (!lib.exists() && !"load".equals(action)) {
    System.err.println("Native lib missing; use `profiler load <path>`");
}

Type guard

null

Try / catch

try {
    profiler.start(...);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("libasyncProfiler")) {
        // load a custom lib then retry
        profiler = AsyncProfiler.getInstance("/path/to/libasyncProfiler.so");
    } else throw e;
}

Prevention

Ship/verify the bundled libasyncProfiler native lib with your arthas distribution.
Use `profiler load <abs-path>` for a custom-built native lib.
Match the native lib to your OS/arch.

When it happens

Trigger: Running `profiler start` (or status/resume/stop/etc.) on Linux/Mac when the bundled libasyncProfiler native library is absent from the arthas install directory. Occurs with stripped-down or partial arthas distributions, or when the working directory does not contain the lib.

Common situations: Using a minimal/custom arthas packaging that omits the native lib; running arthas from a directory that does not contain the async-profiler .so/.dylib; the lib file was deleted or not extracted; permissions issue preventing the lib from being read.

Related errors

AI-assisted analysis of alibaba/arthas@21cf2e9ba5 (2026-08-14). Data as JSON: /api/errors/e6ffb50be02dafaa. Report an issue: GitHub.