pinpoint-apm/pinpoint · critical · RuntimeException

Failed to detect pinpoint profile. Please add -Dpinpoint.act

Error message

Failed to detect pinpoint profile. Please add -Dpinpoint.active.profile=<profile> to VM option. Valid profiles are "<supportedProfiles>". Profile aliases are defined in pinpoint-root.config with the format: pinpoint.profile.alias.<profile>=<alias1>,<alias2>...

What it means

Thrown by ProfilePropertyLoader.getActiveProfile when the pinpoint.active.profile key is absent from the resolved default properties (and not supplied as a VM option). Pinpoint requires an explicit active profile to select which profile config files to load, so startup aborts with guidance on the valid profiles and alias mechanism.

Source

Thrown at agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/config/ProfilePropertyLoader.java:122

        loadProperties(defaultProperties, this.javaSystemProperty);

        // root path
        saveAgentRootPath(agentRootPath, defaultProperties);

        // log path
        return defaultProperties;
    }

    private void saveAgentRootPath(Path agentRootPath, Properties properties) {
        properties.put(AGENT_ROOT_PATH_KEY, agentRootPath);
        logger.info(String.format("agent root path:%s", agentRootPath));
    }


    private String getActiveProfile(Properties defaultProperties) {
        String profile = getProfileProperties(defaultProperties, ProfileConstants.ACTIVE_PROFILE_KEY);
        if (profile == null) {
            throw new RuntimeException("Failed to detect pinpoint profile. Please add -D" +
                    ProfileConstants.ACTIVE_PROFILE_KEY +
                    "=<profile> to VM option. Valid profiles are \"" + supportedProfiles + "\". " +
                    "Profile aliases are defined in pinpoint-root.config with the format: " +
                    ProfileConstants.PROFILE_ALIAS_KEY_PREFIX + "<profile>=<alias1>,<alias2>..."
            );
        }

        // prevent directory traversal attack
        for (Path supportedProfile : supportedProfiles) {
            if (supportedProfile.toString().equalsIgnoreCase(profile)) {
                return supportedProfile.toString();
            }
        }

        // handle alias
        for (Path supportedProfile : supportedProfiles) {
            String supportedProfileName = supportedProfile.toString();
            String aliasesStr = getProfileProperties(defaultProperties, ProfileConstants.PROFILE_ALIAS_KEY_PREFIX + supportedProfileName);

View on GitHub (pinned to 744c3d3075)

Solutions

  1. Add -Dpinpoint.active.profile=release (or local/test) to the target JVM's options
  2. Set pinpoint.active.profile=<profile> in pinpoint-root.config so it is picked up from properties
  3. Check the message's supportedProfiles list and use one of those values or a defined alias
  4. When using the PinpointAgent/agent-dir start scripts, ensure the profile VM option is passed through, e.g. via $PINPOINT_AGENT_VM_ARGS or the script's profile flag

Example fix

// before
java -javaagent:pinpoint-bootstrap.jar -jar app.jar // no profile specified
// after
java -javaagent:pinpoint-bootstrap.jar -Dpinpoint.active.profile=release -jar app.jar
Defensive patterns

Strategy: validation

Validate before calling

String profile = System.getProperty("pinpoint.active.profile");
if (profile == null || profile.isEmpty()) { throw new IllegalStateException("set -Dpinpoint.active.profile=local|test|release"); }

Try / catch

try { startAgent(args); } catch (RuntimeException e) { if (e.getMessage().contains("Failed to detect pinpoint profile")) { log.error("add -Dpinpoint.active.profile=<profile> to JVM options"); } throw e; }

Prevention

When it happens

Trigger: Starting the pinpoint agent without -Dpinpoint.active.profile=<profile> and without that key defined in the root config files (pinpoint-root.config).

Common situations: Fresh agent installation not yet configured; upgrading agents and the old config lacked the profile key; copying pinpoint.config without the root profile settings; CI containers launched with minimal VM options.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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