pinpoint-apm/pinpoint · error

Agent Directory Verify fail. skipping agent loading.

Error message

Agent Directory Verify fail. skipping agent loading.

What it means

AgentDirBaseClassPathResolver failed to produce an AgentDirectory, meaning the agent directory layout could not be verified (missing boot jars, plugin dirs, or malformed agent home). The bootstrap logs this warning and skips agent loading entirely.

Source

Thrown at agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/PinpointBootStrap.java:99

        final Path agentPath = javaAgentPathResolver.resolveJavaAgentPath();
        logger.info("JavaAgentPath:" + agentPath);
        if (!Files.exists(agentPath)) {
            logger.warn("AgentPath not found path:" + agentPath);
        }

        if (Object.class.getClassLoader() != PinpointBootStrap.class.getClassLoader()) {
            // TODO bug : location is null
            logger.warn("Invalid pinpoint-bootstrap.jar:" + agentArgs);
            return;
        }

        final Map<String, String> agentArgsMap = argsToMap(agentArgs);

        final ClassPathResolver classPathResolver = new AgentDirBaseClassPathResolver(agentPath);

        final AgentDirectory agentDirectory = resolveAgentDir(classPathResolver);
        if (agentDirectory == null) {
            logger.warn("Agent Directory Verify fail. skipping agent loading.");
            logPinpointAgentLoadFail();
            return;
        }
        BootDir bootDir = agentDirectory.getBootDir();
        appendToBootstrapClassLoader(instrumentation, bootDir);

        ClassLoader parentClassLoader = getParentClassLoader();
        PinpointStarter bootStrap = new PinpointStarter(instrumentation, parentClassLoader, agentArgsMap, agentDirectory);
        if (!bootStrap.start()) {
            logPinpointAgentLoadFail();
        }
    }

    private AgentDirectory resolveAgentDir(ClassPathResolver classPathResolver) {
        try {
            return classPathResolver.resolve();
        } catch (Exception e) {
            logger.warn("AgentDir resolve fail Caused by:" + e.getMessage(), e);

View on GitHub (pinned to 744c3d3075)

Solutions

1. Deploy the complete, unmodified pinpoint-agent distribution directory and point -javaagent at the bootstrap jar inside it
2. Check the agent directory contains the expected boot jars and plugins folders
3. Don't mix versions — replace the whole agent dir on upgrade
4. Enable/inspect bootstrap logs around AgentDirBaseClassPathResolver to see which path check failed

Example fix

// before
java -javaagent:/opt/agent/pinpoint-bootstrap.jar -jar app.jar   # only the jar was copied
// after
java -javaagent:/opt/pinpoint-agent-2.5.3/pinpoint-bootstrap.jar -jar app.jar   # full distribution

// shell: sanity-check agent directory layout before launch
AGENT_DIR=/opt/pinpoint-agent-2.5.3
for d in boot plugins lib; do [ -d "$AGENT_DIR/$d" ] || echo "missing $AGENT_DIR/$d"; done
[ -f "$AGENT_DIR/pinpoint.config" ] || echo "missing pinpoint.config"

When it happens

Trigger: The -javaagent jar's parent directory lacks the expected Pinpoint layout (boot/, plugins/, lib/); version mismatch where the bootstrap jar is new but the agent dir contents are old; the directory was partially copied or cleaned up.

Common situations: Extracting only pinpoint-bootstrap.jar from the agent distribution instead of the whole pinpoint-agent-x.y.z folder; mixing files from two agent versions after an in-place upgrade; CI copying an incomplete agent directory into the image.

Related errors

• AgentPath not found path:
• PinPoint is disabled via Env/Property.
• pinpoint-bootstrap already started. skipping agent loading.
• Invalid pinpoint-bootstrap.jar:
• AgentDir resolve fail Caused by:

AI-assisted analysis of pinpoint-apm/pinpoint@744c3d3075 (2026-09-07). Data as JSON: /api/errors/00fe06a0c1dbaf17. Report an issue: GitHub.