{"record":{"id":"19959d25c4b4143f","repo":"pinpoint-apm/pinpoint","slug":"agentdirpath-is-null","errorCode":null,"errorMessage":"agentDirPath is null ","messagePattern":"agentDirPath is null ","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/agentdir/AgentDirBaseClassPathResolver.java","lineNumber":94,"sourceCode":"\n        final BootDir bootDir = resolveBootDir(agentDirPath);\n\n        final Path agentLibPath = getAgentLibPath(agentDirPath);\n        final List<Path> libs = resolveLib(agentLibPath);\n\n        Path agentPluginPath = getAgentPluginPath(agentDirPath);\n        final List<Path> plugins = resolvePlugins(agentPluginPath);\n\n        final AgentDirectory agentDirectory =\n                new AgentDirectory(bootstrapJarName, this.bootstrapJarPath, agentDirPath, bootDir, libs, plugins);\n\n        return agentDirectory;\n    }\n\n    private Path getAgentDirPath(Path agentJarFullPath) {\n        Path agentDirPathStr = agentJarFullPath.getParent();\n        if (agentDirPathStr == null) {\n            throw new IllegalStateException(\"agentDirPath is null \" + agentJarFullPath);\n        }\n\n        logger.info(\"Agent original-path:\" + agentDirPathStr);\n        // defense alias change\n\n        Path agentDirPath = FileUtils.toRealPath(agentDirPathStr);\n        logger.info(\"Agent real-path:\" + agentDirPath);\n        return agentDirPath;\n    }\n\n\n    private BootDir resolveBootDir(Path agentDirPath) {\n        Path bootDirPath = agentDirPath.resolve(\"boot\");\n        return new BootDir(bootDirPath, bootJarDescriptions);\n    }\n\n    public List<JarDescription> getBootJarDescriptions() {\n        return Collections.unmodifiableList(bootJarDescriptions);","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/agentdir/AgentDirBaseClassPathResolver.java#L76-L112","documentation":"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.","triggerScenarios":"Passing a bootstrap jar path with no parent component (bare filename or root-relative path) so agentJarFullPath.getParent() returns null.","commonSituations":"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.","solutions":["Use an absolute path for -javaagent (e.g. /opt/pinpoint-agent/pinpoint-bootstrap.jar)","Ensure the path resolves to a location with a parent directory under a real filesystem root","In launchers, canonicalize the jar path to an absolute Path before constructing the resolver"],"exampleFix":"// before\n-javaagent:pinpoint-bootstrap.jar\n// after\n-javaagent:/opt/pinpoint-agent/pinpoint-bootstrap.jar","handlingStrategy":"validation","validationCode":"Path boot = Paths.get(agentJarArg).toAbsolutePath();\nif (boot.getParent() == null) {\n    throw new IllegalArgumentException(\"agent jar path must have a parent dir: \" + boot);\n}","typeGuard":"boolean hasParentDir(Path p) {\n    return p != null && p.getParent() != null;\n}","tryCatchPattern":"try {\n    AgentDirectory dir = resolver.resolve();\n} catch (IllegalStateException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"agentDirPath is null\")) {\n        // convert to absolute path and retry once\n    }\n    throw e;\n}","preventionTips":["Always use absolute paths for -javaagent","Canonicalize paths with toAbsolutePath().normalize() before passing them to launchers","Document the absolute-path requirement in deployment scripts"],"tags":["java","null-value","path-resolution","agent-bootstrap"],"backgroundTag":"null-argument","analyzedSha":"744c3d3075e595656abb1ae331ad2c0e4c9eb996","analyzedAt":"2026-09-07T18:48:45.289Z","contentChangedAt":"2026-09-07T18:48:45.289Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}