alibaba/arthas · error · IllegalStateException

Can not find libasyncProfiler so, please check the arthas…

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.

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.

Appendix: 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)