pinpoint-apm/pinpoint · error · IllegalStateException

agentDirPath is null

Error message

agentDirPath is null 

What it means

getAgentDirPath() derives the agent directory from the bootstrap jar path via Path.getParent(). If the jar path has no parent (e.g. a bare filename resolved against no meaningful filesystem root), it throws IllegalStateException 'agentDirPath is null <path>'. Pinpoint needs a concrete parent directory to resolve boot/lib/profile directories.

Source

Thrown at agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/agentdir/AgentDirBaseClassPathResolver.java:94

        final BootDir bootDir = resolveBootDir(agentDirPath);

        final Path agentLibPath = getAgentLibPath(agentDirPath);
        final List<Path> libs = resolveLib(agentLibPath);

        Path agentPluginPath = getAgentPluginPath(agentDirPath);
        final List<Path> plugins = resolvePlugins(agentPluginPath);

        final AgentDirectory agentDirectory =
                new AgentDirectory(bootstrapJarName, this.bootstrapJarPath, agentDirPath, bootDir, libs, plugins);

        return agentDirectory;
    }

    private Path getAgentDirPath(Path agentJarFullPath) {
        Path agentDirPathStr = agentJarFullPath.getParent();
        if (agentDirPathStr == null) {
            throw new IllegalStateException("agentDirPath is null " + agentJarFullPath);
        }

        logger.info("Agent original-path:" + agentDirPathStr);
        // defense alias change

        Path agentDirPath = FileUtils.toRealPath(agentDirPathStr);
        logger.info("Agent real-path:" + agentDirPath);
        return agentDirPath;
    }


    private BootDir resolveBootDir(Path agentDirPath) {
        Path bootDirPath = agentDirPath.resolve("boot");
        return new BootDir(bootDirPath, bootJarDescriptions);
    }

    public List<JarDescription> getBootJarDescriptions() {
        return Collections.unmodifiableList(bootJarDescriptions);

View on GitHub (pinned to 744c3d3075)

Solutions

1. Use an absolute path for -javaagent (e.g. /opt/pinpoint-agent/pinpoint-bootstrap.jar)
2. Ensure the path resolves to a location with a parent directory under a real filesystem root
3. In launchers, canonicalize the jar path to an absolute Path before constructing the resolver

Example fix

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

Path boot = Paths.get(agentJarArg).toAbsolutePath();
if (boot.getParent() == null) {
    throw new IllegalArgumentException("agent jar path must have a parent dir: " + boot);
}

boolean hasParentDir(Path p) {
    return p != null && p.getParent() != null;
}

try {
    AgentDirectory dir = resolver.resolve();
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("agentDirPath is null")) {
        // convert to absolute path and retry once
    }
    throw e;
}

When it happens

Trigger: Passing a bootstrap jar path with no parent component (bare filename or root-relative path) so agentJarFullPath.getParent() returns null.

Common situations: Launching with -javaagent:pinpoint-bootstrap.jar relying on a working directory instead of an absolute path; exotic path construction in embedded launchers; unusual filesystem roots.

Related errors

• not found
• not found.
• lib dir is empty
• can read
• !/ not found

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