apache/cassandra · error · IllegalStateException

Unable to get an instance of Async-Profiler

Error message

Unable to get an instance of Async-Profiler

What it means

getProfiler wraps AsyncProfiler.getInstance() and converts any failure (missing native library, unsupported platform, attach error) into IllegalStateException('Unable to get an instance of Async-Profiler') with the original cause attached. This runs during AsyncProfilerService construction, so the service ends up with a null profiler.

Solutions

1. Install the async-profiler native library matching the platform and make it loadable (java.library.path / LD_LIBRARY_PATH)
2. Check the chained cause ('Caused by') in the logs for the exact load failure
3. Disable async_profiler_enabled if profiling is not needed on this node
4. Confirm JDK compatibility with the installed async-profiler version

Example fix

// before (missing lib)
java ... // no agentpath, getInstance() fails
// after
java -agentpath:/usr/lib/async-profiler/libasyncProfiler.so ...

try { Class.forName("one.profiler.AsyncProfiler"); } catch (ClassNotFoundException e) { /* async-profiler jar not present */ }

try { service.status(); } catch (IllegalStateException | RuntimeException e) { logger.error("Async profiler unusable: {}", e.getMessage(), e.getCause()); }

When it happens

Trigger: AsyncProfilerService construction when AsyncProfiler.getInstance() throws — typically because libasyncProfiler.so is not on the JVM library path, or the JVM/platform is unsupported.

Common situations: Installing Cassandra without the async-profiler native library; wrong library architecture (e.g. aarch64 lib on x86_64); JDKs where async-profiler attach is unsupported.

Related errors

• Async profiler not available.
• Async-profiler experience likely affected. Kernel symbols…
• Async Profiler is not enabled. Enable it by setting
• Cannot initialize class
• Cluster metadata is already initialized to

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/80ef471b4def1b0e. Report an issue: GitHub.

Appendix: source

Thrown at src/java/org/apache/cassandra/service/AsyncProfilerService.java:530

        public abstract B apply(AsyncProfiler a) throws Throwable;
    }

    private AsyncProfiler getProfiler()
    {
        if (!ASYNC_PROFILER_ENABLED.getBoolean())
            return null;

        if (asyncProfiler != null)
            return asyncProfiler;

        try
        {
            asyncProfiler = AsyncProfiler.getInstance();
            return asyncProfiler;
        }
        catch (Throwable t)
        {
            throw new IllegalStateException("Unable to get an instance of Async-Profiler", t);
        }
    }

    @VisibleForTesting
    public static void reset()
    {
        if (instance != null)
            asyncProfiler = null;

        instance = null;
    }
}

View on GitHub (pinned to 88fd0f6a0e)