pinpoint-apm/pinpoint · error · IllegalArgumentException

invalid pinpoint.agentName=${agentName}

Error message

invalid pinpoint.agentName=${agentName}

What it means

OtlpTraceMapperUtils.getAgentNameOverride reads the 'pinpoint.agentName' span/resource attribute as an agent-name override and validates it with IdValidateUtils.validateId against PinpointConstants.AGENT_NAME_MAX_LEN_V4. If the value is present but fails Pinpoint's ID rules (length or character set), IllegalArgumentException is thrown, rejecting the span batch.

Source

Thrown at otlptrace/otlptrace-collector/src/main/java/com/navercorp/pinpoint/otlp/trace/collector/mapper/OtlpTraceMapperUtils.java:102

    public static IdAndName getId(Map<String, AttributeValue> attributes, boolean allowApplicationNameFallback) {
        final String applicationName = getApplicationName(attributes);
        final String agentNameOverride = getAgentNameOverride(attributes);
        final AgentAuth agentAuth = getAgentAuth(attributes, agentNameOverride, applicationName, allowApplicationNameFallback);
        final String serviceName = getServiceName(attributes);
        return new IdAndName(agentAuth.agentId(), agentAuth.agentName(), applicationName, serviceName);
    }

    private static String resolveAgentName(String agentNameOverride, String defaultName) {
        return agentNameOverride != null ? agentNameOverride : defaultName;
    }

    private static String getAgentNameOverride(Map<String, AttributeValue> attributes) {
        final String agentName = AttributeUtils.getAttributeStringValue(attributes, KEY_AGENT_NAME, null);
        if (agentName == null) {
            return null;
        }
        if (!IdValidateUtils.validateId(agentName, PinpointConstants.AGENT_NAME_MAX_LEN_V4)) {
            throw new IllegalArgumentException("invalid pinpoint.agentName=" + agentName);
        }
        return agentName;
    }

    public static String getApplicationName(Map<String, AttributeValue> attributes) {
        String applicationName = AttributeUtils.getAttributeStringValue(attributes, KEY_APPLICATION_NAME, null);
        if (applicationName == null) {
            applicationName = AttributeUtils.getAttributeStringValue(attributes, KEY_SERVICE_NAME, null);
            if (applicationName == null) {
                throw new IllegalArgumentException("not found applicationName");
            }
        }
        if (!IdValidateUtils.validateId(applicationName, PinpointConstants.APPLICATION_NAME_MAX_LEN_V3)) {
            throw new IllegalArgumentException("invalid applicationName=" + applicationName);
        }

        return applicationName;
    }

View on GitHub (pinned to 744c3d3075)

Solutions

1. Change the pinpoint.agentName attribute value to conform to Pinpoint agent-name rules: within AGENT_NAME_MAX_LEN_V4 and using allowed characters (alphanumerics, '-', '_', '.').
2. Truncate or sanitize the value where the attribute is injected (e.g. k8s metadata enrichment) before export.
3. Remove the pinpoint.agentName attribute entirely if the default agent identification is sufficient (null is accepted and skips the override).
4. Pre-validate client-side with the same rule (length + allowed charset) before attaching the attribute.

Example fix

// before
attributes.put("pinpoint.agentName", "my agent / prod#1"); // illegal chars
// after
attributes.put("pinpoint.agentName", "my-agent-prod-1");

String agentName = attributes.get("pinpoint.agentName");
if (agentName != null && !agentName.matches("[a-zA-Z0-9._-]{1," + AGENT_NAME_MAX_LEN_V4 + "}")) {
    throw new IllegalArgumentException("agentName violates Pinpoint naming rules: " + agentName);
}

boolean isSafeAgentNameOverride(Map<String, AttributeValue> attrs) {
    String v = AttributeUtils.getAttributeStringValue(attrs, "pinpoint.agentName", null);
    return v == null || IdValidateUtils.validateId(v, PinpointConstants.AGENT_NAME_MAX_LEN_V4);
}

try {
    mapper.mapSpan(span);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("invalid pinpoint.agentName")) {
        log.warn("dropping invalid agentName override: {}", e.getMessage());
    } else { throw e; }
}

When it happens

Trigger: Sending OTLP spans carrying the pinpoint.agentName attribute whose value is empty, longer than AGENT_NAME_MAX_LEN_V4, or contains characters disallowed by Pinpoint's agent ID naming rules.

Common situations: Users configuring agentName overrides with spaces, slashes, or other special characters; long k8s pod-derived names exceeding the max length; configuration templating mistakes that leave the attribute empty; upgrading to V4 naming rules that are stricter than what old exporters emit.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• Resource attribute `service.name` is required to save OTLP m
• Resource attribute `pinpoint.agentId` is required to save OT
• invalid traceId: ${error}
• invalid spanId: ${error}
• annotationKey name must not be empty

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