pinpoint-apm/pinpoint · error

AgentDir resolve fail Caused by:

Error message

AgentDir resolve fail Caused by:

What it means

resolveAgentDir wraps classPathResolver.resolve() and catches any exception, logging 'AgentDir resolve fail Caused by:' plus the underlying exception message, then returns null so agent loading is skipped. The real cause is in the chained exception's message (path parsing, missing files, malformed layout).

Source

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

            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);
            return null;
        }
    }


    private ClassLoader getParentClassLoader() {
        final ClassLoader classLoader = getPinpointBootStrapClassLoader();
        if (classLoader == Object.class.getClassLoader()) {
            logger.info("parentClassLoader:BootStrapClassLoader:" + classLoader);
        } else {
            logger.info("parentClassLoader:" + classLoader);
        }
        return classLoader;
    }

    private ClassLoader getPinpointBootStrapClassLoader() {
        return PinpointBootStrap.class.getClassLoader();
    }

View on GitHub (pinned to 744c3d3075)

Solutions

1. Read the chained exception in the log to see the exact failing path/file
2. Verify the agent directory layout matches the distribution for your Pinpoint version
3. Check file/directory read permissions for the JVM user
4. Re-extract the agent distribution cleanly and update -javaagent to the new path

// shell: verify jar and layout before launch
[ -f "$AGENT_DIR/pinpoint-bootstrap.jar" ] && [ -f "$AGENT_DIR/pinpoint.config" ] && [ -r "$AGENT_DIR" ] || echo "agent dir incomplete or unreadable"

When it happens

Trigger: resolve() throws because the agent path is not a jar, the config file (pinpoint.config) is missing from the agent dir, or expected subdirectories cannot be located.

Common situations: Renaming/reshaping the agent directory; pointing -javaagent at a thin wrapper jar without the surrounding layout; permissions preventing directory reads; corrupted extraction of the agent archive.

Related errors

• agentDirPath is null
• PinPoint is disabled via Env/Property.
• pinpoint-bootstrap already started. skipping agent loading.
• AgentPath not found path:
• Invalid pinpoint-bootstrap.jar:

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