What causes "AgentPath not found path:" in pinpoint-apm/pinpoint?

Verify the path printed in the warning exists on the host and is readable by the JVM user

AgentPath not found path:

Error message

AgentPath not found path:

What it means

During bootstrap start, the agent resolves the path of pinpoint-bootstrap.jar from the javaagent command-line argument and checks it exists on disk. If not, a warning is logged. The load usually fails shortly after (dependency jars can't be located), so this points to an agent installation path problem.

Source

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

    private final String agentArgs;
    private final Instrumentation instrumentation;

    private PinpointBootStrap(String agentArgs, Instrumentation instrumentation) {
        this.agentArgs = agentArgs;
        this.instrumentation = Objects.requireNonNull(instrumentation, "instrumentation");
    }


    private void start() {
        logger.info("pinpoint agentArgs:" + agentArgs);
        logger.info("PinpointBootStrap.ClassLoader:" + PinpointBootStrap.class.getClassLoader());
        logger.info("ContextClassLoader:" + Thread.currentThread().getContextClassLoader());

        final JavaAgentPathResolver javaAgentPathResolver = JavaAgentPathResolver.newJavaAgentPathResolver();
        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;
        }

View on GitHub (pinned to 744c3d3075)

Solutions

Verify the path printed in the warning exists on the host and is readable by the JVM user
Fix the -javaagent argument to an absolute path to pinpoint-bootstrap.jar
Ensure the full agent directory (not just the bootstrap jar) is present next to the jar
Restart the application after fixing the path — the agent path is captured at JVM launch

Example fix

// before
java -javaagent:./pinpoint-agent/pinpoint-bootstrap.jar -jar app.jar
// after
java -javaagent:/opt/pinpoint-agent/pinpoint-bootstrap.jar -jar app.jar

Defensive patterns

Strategy: validation

Validate before calling

// shell: before launching
AGENT_JAR=/opt/pinpoint-agent/pinpoint-bootstrap.jar
[ -f "$AGENT_JAR" ] || echo "agent jar missing: $AGENT_JAR"

Prevention

Use absolute paths for -javaagent
Mount the full agent directory at a fixed path in containers
Recreate the JVM (not just the agent) after moving files, since the path is captured at launch

When it happens

Trigger: The jar passed to -javaagent was moved/renamed/deleted after JVM start parameter capture; a relative path that no longer resolves; agent directory restructured by an upgrade; the jar lives inside a container image layer that was pruned.

Common situations: Upgrading Pinpoint while the old JVM process is still running; mounting the agent dir at a different path in Docker than the -javaagent argument assumes; typos or spaces in the -javaagent path; fat-jar bundling that repackages the bootstrap jar.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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