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.

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.

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