pinpoint-apm/pinpoint · error · IllegalArgumentException

Unknown AgentType:

Error message

Unknown AgentType:

What it means

AgentType.getAgentType(agentTypeName) iterates AgentType.values() with equalsIgnoreCase and throws IllegalArgumentException 'Unknown AgentType:<name>' when nothing matches. It is called from AgentType.of(agentArgs), which reads the agent-type key from the agent args, so an unrecognized or misspelled agentType string aborts agent initialization.

Source

Thrown at agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/AgentType.java:58

    @Override
    public String toString() {
        return "AgentType{"
                + className +
                '}';
    }

    public static AgentType getAgentType(String agentTypeName) {
        if (agentTypeName == null) {
            return AgentType.DEFAULT_AGENT;
        }

        for (AgentType agentType : AgentType.values()) {
            if (agentType.name().equalsIgnoreCase(agentTypeName)) {
                return agentType;
            }
        }
        throw new IllegalArgumentException("Unknown AgentType:" + agentTypeName);
    }

    public static AgentType of(Function<String, String> agentArgs) {
        String agentTypeString = agentArgs.apply(AGENT_TYPE_KEY);
        if (agentTypeString == null) {
            agentTypeString = AgentType.DEFAULT_AGENT.name();
        }
        return getAgentType(agentTypeString);
    }
}

View on GitHub (pinned to 744c3d3075)

Solutions

1. Print the configured agentType value and compare against the AgentType enum constants of your Pinpoint version
2. Remove the agentType argument entirely to fall back to DEFAULT_AGENT
3. If you need a custom type, add an AgentType enum constant (with matching code) in your fork instead of passing an unknown string
4. Align the value with the docs for your exact Pinpoint version — names changed across releases

Example fix

// before
-Dpinpoint.agentType=AGENT_TYPE_MAIN_SECURED
// after
-Dpinpoint.agentType=AGENT_TYPE (or omit to use DEFAULT_AGENT)

String requested = agentArgs.apply(AGENT_TYPE_KEY);
if (requested != null && Arrays.stream(AgentType.values()).noneMatch(t -> t.name().equalsIgnoreCase(requested))) {
    logger.warn("Unknown agentType '{}', falling back to DEFAULT_AGENT", requested);
    requested = AgentType.DEFAULT_AGENT.name();
}

When it happens

Trigger: Passing a value for AGENT_TYPE_KEY in the agent args (or -Dpinpoint.agentType) that is not one of the enum constants (case-insensitive), e.g. 'ANNOTATED_AGENT' when only DEFAULT_AGENT etc. exist, or an empty string.

Common situations: Upgrading Pinpoint where an old agentType name was removed or renamed; copying launch configs between agent editions (e.g. Google/Thrift variants); hand-edited JVM args with a typo; spaces around the value in a launcher script.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Failed to detect pinpoint profile. Please add -Dpinpoint.act
• Unknown SpanSenderType: ${value}
• boot method invoke failed. Error:
• boot class not found. bootClass: Error:
• unsupported profile or profile alias:

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