{"record":{"id":"00fe06a0c1dbaf17","repo":"pinpoint-apm/pinpoint","slug":"agent-directory-verify-fail-skipping-agent-loadin","errorCode":null,"errorMessage":"Agent Directory Verify fail. skipping agent loading.","messagePattern":"Agent Directory Verify fail\\. skipping agent loading\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/PinpointBootStrap.java","lineNumber":99,"sourceCode":"        final Path agentPath = javaAgentPathResolver.resolveJavaAgentPath();\n        logger.info(\"JavaAgentPath:\" + agentPath);\n        if (!Files.exists(agentPath)) {\n            logger.warn(\"AgentPath not found path:\" + agentPath);\n        }\n\n        if (Object.class.getClassLoader() != PinpointBootStrap.class.getClassLoader()) {\n            // TODO bug : location is null\n            logger.warn(\"Invalid pinpoint-bootstrap.jar:\" + agentArgs);\n            return;\n        }\n\n        final Map<String, String> agentArgsMap = argsToMap(agentArgs);\n\n        final ClassPathResolver classPathResolver = new AgentDirBaseClassPathResolver(agentPath);\n\n        final AgentDirectory agentDirectory = resolveAgentDir(classPathResolver);\n        if (agentDirectory == null) {\n            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);","sourceCodeStart":81,"sourceCodeEnd":117,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/PinpointBootStrap.java#L81-L117","documentation":"AgentDirBaseClassPathResolver failed to produce an AgentDirectory, meaning the agent directory layout could not be verified (missing boot jars, plugin dirs, or malformed agent home). The bootstrap logs this warning and skips agent loading entirely.","triggerScenarios":"The -javaagent jar's parent directory lacks the expected Pinpoint layout (boot/, plugins/, lib/); version mismatch where the bootstrap jar is new but the agent dir contents are old; the directory was partially copied or cleaned up.","commonSituations":"Extracting only pinpoint-bootstrap.jar from the agent distribution instead of the whole pinpoint-agent-x.y.z folder; mixing files from two agent versions after an in-place upgrade; CI copying an incomplete agent directory into the image.","solutions":["Deploy the complete, unmodified pinpoint-agent distribution directory and point -javaagent at the bootstrap jar inside it","Check the agent directory contains the expected boot jars and plugins folders","Don't mix versions — replace the whole agent dir on upgrade","Enable/inspect bootstrap logs around AgentDirBaseClassPathResolver to see which path check failed"],"exampleFix":"// before\njava -javaagent:/opt/agent/pinpoint-bootstrap.jar -jar app.jar   # only the jar was copied\n// after\njava -javaagent:/opt/pinpoint-agent-2.5.3/pinpoint-bootstrap.jar -jar app.jar   # full distribution","handlingStrategy":"validation","validationCode":"// shell: sanity-check agent directory layout before launch\nAGENT_DIR=/opt/pinpoint-agent-2.5.3\nfor d in boot plugins lib; do [ -d \"$AGENT_DIR/$d\" ] || echo \"missing $AGENT_DIR/$d\"; done\n[ -f \"$AGENT_DIR/pinpoint.config\" ] || echo \"missing pinpoint.config\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Deploy the whole distribution directory, never just the bootstrap jar","Replace the entire agent directory on upgrades — never merge versions","Add a container/build-time check of the agent layout"],"tags":["java","javaagent","directory","deployment"],"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"}