pinpoint-apm/pinpoint · error · IllegalStateException

'log4j2-agent.xml' not found. agentPath:${profilePath}

Error message

'log4j2-agent.xml' not found. agentPath:${profilePath}

What it means

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.

Source

Thrown at agent-module/profiler-logging/src/main/java/com/navercorp/pinpoint/profiler/logging/Log4j2LoggingSystem.java:45

    private LoggerContext loggerContext;
    private final Path configLocation;

    private PluginLoggerBinder binder;


    public static Log4j2LoggingSystem searchPath(Path agentPath) {
        Path configPath = getConfiguration(agentPath);
        return new Log4j2LoggingSystem(configPath);
    }

    private static Path getConfiguration(Path profilePath) {
        for (String configFile : LOOKUP) {
            Path configLocation = profilePath.resolve(configFile);
            if (Files.exists(configLocation)) {
                return configLocation;
            }
        }
        throw new IllegalStateException("'log4j2-agent.xml' not found. agentPath:" + profilePath);
    }

    Log4j2LoggingSystem(Path configLocation) {
        this.configLocation = Objects.requireNonNull(configLocation, "configLocation");
    }

    @Override
    public String getConfigLocation() {
        return configLocation.toString();
    }

    @Override
    public void start() {
        // log4j init

        this.loggerContext = getLoggerContext();

        Logger logger = getLoggerContextLogger();

View on GitHub (pinned to 744c3d3075)

Solutions

1. Verify log4j2-agent.xml exists under the agent's active profile directory (e.g. /agent/profiles/release/log4j2-agent.xml)
2. Correct the active profile name (-Dpinpoint.profiler.profiles.active=release) to one whose directory contains the config
3. Re-download/extract a complete agent distribution
4. Check the resolved profilePath in the message and compare against the actual directory layout

Example fix

# before (missing file)
/agent/profiles/release/            # no log4j2-agent.xml
# after
/agent/profiles/release/log4j2-agent.xml  # restore the config from the original distribution

Path profilePath = Paths.get(agentHome, "profiles", activeProfile);
Path cfg = profilePath.resolve("log4j2-agent.xml");
if (!Files.exists(cfg)) {
    throw new IllegalStateException("missing log4j2-agent.xml under " + profilePath);
}

try {
    Log4j2LoggingSystem system = Log4j2LoggingSystem.getConfiguration();
} catch (IllegalStateException e) {
    logger.fatal("agent logging config missing: {}", e.getMessage());
    throw e; // logging config is mandatory for the agent
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Config file not found": what it means and how to fix it in docker-sync, Maven, Vagrant, Turborepo and other tools — this error's family across 60 libraries.

Related errors

• intervalMillis must be positive: ${intervalMillis}
• Could not find file.(path:+filePath+)
• LoggerBinder is already initialized
• LoggerBinder is already initialized
• - agentId: {}

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