{"record":{"id":"b21b158b643fcdf4","repo":"pinpoint-apm/pinpoint","slug":"agentdir-resolve-fail-caused-by","errorCode":null,"errorMessage":"AgentDir resolve fail Caused by:","messagePattern":"AgentDir resolve fail Caused by:","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/PinpointBootStrap.java","lineNumber":117,"sourceCode":"            logger.warn(\"Agent Directory Verify fail. skipping agent loading.\");\n            logPinpointAgentLoadFail();\n            return;\n        }\n        BootDir bootDir = agentDirectory.getBootDir();\n        appendToBootstrapClassLoader(instrumentation, bootDir);\n\n        ClassLoader parentClassLoader = getParentClassLoader();\n        PinpointStarter bootStrap = new PinpointStarter(instrumentation, parentClassLoader, agentArgsMap, agentDirectory);\n        if (!bootStrap.start()) {\n            logPinpointAgentLoadFail();\n        }\n    }\n\n    private AgentDirectory resolveAgentDir(ClassPathResolver classPathResolver) {\n        try {\n            return classPathResolver.resolve();\n        } catch (Exception e) {\n            logger.warn(\"AgentDir resolve fail Caused by:\" + e.getMessage(), e);\n            return null;\n        }\n    }\n\n\n    private ClassLoader getParentClassLoader() {\n        final ClassLoader classLoader = getPinpointBootStrapClassLoader();\n        if (classLoader == Object.class.getClassLoader()) {\n            logger.info(\"parentClassLoader:BootStrapClassLoader:\" + classLoader);\n        } else {\n            logger.info(\"parentClassLoader:\" + classLoader);\n        }\n        return classLoader;\n    }\n\n    private ClassLoader getPinpointBootStrapClassLoader() {\n        return PinpointBootStrap.class.getClassLoader();\n    }","sourceCodeStart":99,"sourceCodeEnd":135,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/PinpointBootStrap.java#L99-L135","documentation":"resolveAgentDir wraps classPathResolver.resolve() and catches any exception, logging 'AgentDir resolve fail Caused by:' plus the underlying exception message, then returns null so agent loading is skipped. The real cause is in the chained exception's message (path parsing, missing files, malformed layout).","triggerScenarios":"resolve() throws because the agent path is not a jar, the config file (pinpoint.config) is missing from the agent dir, or expected subdirectories cannot be located.","commonSituations":"Renaming/reshaping the agent directory; pointing -javaagent at a thin wrapper jar without the surrounding layout; permissions preventing directory reads; corrupted extraction of the agent archive.","solutions":["Read the chained exception in the log to see the exact failing path/file","Verify the agent directory layout matches the distribution for your Pinpoint version","Check file/directory read permissions for the JVM user","Re-extract the agent distribution cleanly and update -javaagent to the new path"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// shell: verify jar and layout before launch\n[ -f \"$AGENT_DIR/pinpoint-bootstrap.jar\" ] && [ -f \"$AGENT_DIR/pinpoint.config\" ] && [ -r \"$AGENT_DIR\" ] || echo \"agent dir incomplete or unreadable\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Read the chained 'Caused by' in the log to pinpoint the failing path","Check read permissions on the agent directory for the JVM user","Re-extract the distribution cleanly if paths look wrong"],"tags":["java","javaagent","path-resolution","exception"],"backgroundTag":"directory-not-found","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"}