pinpoint-apm/pinpoint · critical · RuntimeException

lib dir is empty

Error message

 lib dir is empty

What it means

resolveLib() lists jars in the agent's lib directory (filtered by known extensions) and throws RuntimeException '<libPath> lib dir is empty' when the listing is empty. Pinpoint requires plugin/core jars in the lib directory to build the agent class path; an empty lib dir means the installation is incomplete.

Source

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

    }

    private Path getAgentLibPath(Path agentDirPath) {
        return agentDirPath.resolve("lib");
    }

    private Path getAgentPluginPath(Path agentDirPath) {
        return agentDirPath.resolve("plugin");
    }

    private List<Path> resolveLib(Path agentLibPath) {

        if (checkDirectory(agentLibPath)) {
            return Collections.emptyList();
        }

        final List<Path> libFileList = FileUtils.listFiles(agentLibPath, EXTENSIONS);
        if (libFileList.isEmpty()) {
            throw new RuntimeException(agentLibPath + " lib dir is empty");
        }
        // add directory
        libFileList.add(agentLibPath);

        return libFileList;
    }

    private List<Path> resolvePlugins(Path agentPluginPath) {

        if (checkDirectory(agentPluginPath)) {
            logger.warn(agentPluginPath + " is not a directory");
            return Collections.emptyList();
        }

        final List<Path> jars = FileUtils.listFiles(agentPluginPath, "*.jar");
        if (jars.isEmpty()) {
            return Collections.emptyList();
        }

View on GitHub (pinned to 744c3d3075)

Solutions

1. Re-extract the full Pinpoint agent distribution so the lib directory contains its jars
2. Point the agent at the correct agent directory (one that actually has a populated lib folder)
3. Check extension filters: ensure jars are named *.jar and not stripped of extensions
4. Verify no cleanup/AV process deleted the lib contents; restore from the release archive

Example fix

// before
ls /opt/pinpoint-agent/lib  ->  (empty)
// after
tar xzf pinpoint-agent-2.5.0.tar.gz -C /opt/  && ls /opt/pinpoint-agent/lib | head  # jars present

Path lib = Paths.get("/opt/pinpoint-agent/lib");
if (!Files.isDirectory(lib) || listNonEmpty(lib) == false) {
    throw new IllegalStateException("agent lib dir missing or empty: " + lib);
}

boolean listNonEmpty(Path dir) {
    try (var s = Files.list(dir)) { return s.findFirst().isPresent(); }
    catch (IOException e) { return false; }
}

boolean hasLibJars(Path libDir) throws IOException {
    if (libDir == null || !Files.isDirectory(libDir)) return false;
    try (var s = Files.list(libDir)) {
        return s.anyMatch(p -> p.toString().endsWith(".jar"));
    }
}

try {
    AgentDirectory dir = resolver.resolve();
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().endsWith(" lib dir is empty")) {
        // re-extract agent distribution before continuing
    }
    throw e;
}

When it happens

Trigger: agentLibPath exists (passes checkDirectory) but contains no files with the configured extensions (e.g. .jar); FileUtils.listFiles returns an empty list.

Common situations: Partial agent extraction (only config files copied); an antivirus or cleanup job purged the lib folder; pointing the agent at a wrong subdirectory that has an empty lib; failed upgrade leaving lib empty.

Related errors

• not found
• not found.
• agentDirPath is null
• can read
• !/ not found

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