{"record":{"id":"a2dac56f310a4ee0","repo":"pinpoint-apm/pinpoint","slug":"log4j2-agent-xml-not-found-agentpath-profilep","errorCode":null,"errorMessage":"'log4j2-agent.xml' not found. agentPath:${profilePath}","messagePattern":"'log4j2-agent\\.xml' not found\\. agentPath:(.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"agent-module/profiler-logging/src/main/java/com/navercorp/pinpoint/profiler/logging/Log4j2LoggingSystem.java","lineNumber":45,"sourceCode":"    private LoggerContext loggerContext;\n    private final Path configLocation;\n\n    private PluginLoggerBinder binder;\n\n\n    public static Log4j2LoggingSystem searchPath(Path agentPath) {\n        Path configPath = getConfiguration(agentPath);\n        return new Log4j2LoggingSystem(configPath);\n    }\n\n    private static Path getConfiguration(Path profilePath) {\n        for (String configFile : LOOKUP) {\n            Path configLocation = profilePath.resolve(configFile);\n            if (Files.exists(configLocation)) {\n                return configLocation;\n            }\n        }\n        throw new IllegalStateException(\"'log4j2-agent.xml' not found. agentPath:\" + profilePath);\n    }\n\n    Log4j2LoggingSystem(Path configLocation) {\n        this.configLocation = Objects.requireNonNull(configLocation, \"configLocation\");\n    }\n\n    @Override\n    public String getConfigLocation() {\n        return configLocation.toString();\n    }\n\n    @Override\n    public void start() {\n        // log4j init\n\n        this.loggerContext = getLoggerContext();\n\n        Logger logger = getLoggerContextLogger();","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/agent-module/profiler-logging/src/main/java/com/navercorp/pinpoint/profiler/logging/Log4j2LoggingSystem.java#L27-L63","documentation":"Log4j2LoggingSystem.getConfiguration resolves the agent's log4j2 configuration by probing a list of known file names under the profile path (e.g. $PINPOINT_AGENT_PATH/profiles/<profile>/log4j2-agent.xml). If none of the candidate files exist on disk it throws IllegalStateException, because the profiler cannot start logging without a configuration file.","triggerScenarios":"Starting the Pinpoint agent where the active profile directory does not contain any of the LOOKUP config files — typically log4j2-agent.xml is missing from the profile folder, or the profile path itself is wrong.","commonSituations":"Incomplete agent distribution (config file deleted or not packaged); wrong -Dpinpoint.profiler.profiles.active value pointing to a profile dir without configs; running from a stripped/renamed agent directory.","solutions":["Verify log4j2-agent.xml exists under the agent's active profile directory (e.g. /agent/profiles/release/log4j2-agent.xml)","Correct the active profile name (-Dpinpoint.profiler.profiles.active=release) to one whose directory contains the config","Re-download/extract a complete agent distribution","Check the resolved profilePath in the message and compare against the actual directory layout"],"exampleFix":"# before (missing file)\n/agent/profiles/release/            # no log4j2-agent.xml\n# after\n/agent/profiles/release/log4j2-agent.xml  # restore the config from the original distribution","handlingStrategy":"validation","validationCode":"Path profilePath = Paths.get(agentHome, \"profiles\", activeProfile);\nPath cfg = profilePath.resolve(\"log4j2-agent.xml\");\nif (!Files.exists(cfg)) {\n    throw new IllegalStateException(\"missing log4j2-agent.xml under \" + profilePath);\n}","typeGuard":null,"tryCatchPattern":"try {\n    Log4j2LoggingSystem system = Log4j2LoggingSystem.getConfiguration();\n} catch (IllegalStateException e) {\n    logger.fatal(\"agent logging config missing: {}\", e.getMessage());\n    throw e; // logging config is mandatory for the agent\n}","preventionTips":["Verify the active profile directory contains log4j2-agent.xml before starting the agent","Re-extract the full agent distribution if config files are missing","Cross-check the profilePath printed in the error against the real directory tree","Avoid renaming or deleting files inside the agent's profiles folder"],"tags":["logging","log4j2","configuration","file-not-found"],"backgroundTag":"config-file-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"}