pinpoint-apm/pinpoint · error · IllegalArgumentException

invalid pinpoint.agentId=

Error message

invalid pinpoint.agentId=${agentId}

What it means

getAgentAuth resolves the per-instance agentId from span attributes ('pinpoint.agentId' first). If a pinpoint.agentId attribute is present but fails IdValidateUtils.validateId with AGENT_ID_MAX_LEN (length/charset rules), it throws this IllegalArgumentException rather than silently producing a malformed agent identity.

Solutions

1. Correct the pinpoint.agentId attribute to a valid Pinpoint agentId (allowed charset, within AGENT_ID_MAX_LEN)
2. Remove the pinpoint.agentId attribute and let getAgentAuth derive the id from service.instance.id / pod uid / container id / host.name
3. Pre-validate in your exporter with IdValidateUtils.validateId(agentId, PinpointConstants.AGENT_ID_MAX_LEN) before attaching the attribute

Example fix

// before
attributes.put("pinpoint.agentId", "agent-01"); // '-' invalid
// after
attributes.put("pinpoint.agentId", "agent01");

if (agentId != null && !IdValidateUtils.validateId(agentId, PinpointConstants.AGENT_ID_MAX_LEN)) {
    throw new IllegalArgumentException("invalid pinpoint.agentId=" + agentId);
}

try { AgentAuth a = mapperUtils.agentAuth(attrs, override, app, false); } catch (IllegalArgumentException e) { /* reject or fall back to derived id */ }

When it happens

Trigger: Attributes contain a non-null 'pinpoint.agentId' value whose characters or length violate IdValidateUtils.validateId(agentId, PinpointConstants.AGENT_ID_MAX_LEN).

Common situations: Manually configured agentId containing '-' or other disallowed chars; agentId longer than the max length; templated config that interpolated an invalid value (empty string or full hostname).

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

• invalid agentId(derived from applicationName)=
• invalid applicationName=
• invalid host.name=
• invalid =
• invalid pinpoint.agentName=

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

Appendix: source

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

        final String name = scope.getName();
        if (name.isEmpty()) {
            return null;
        }
        final String version = scope.getVersion();
        if (version.isEmpty()) {
            return name;
        }
        return name + '@' + version;
    }

    private record AgentAuth(String agentId, String agentName) {
    }

    private static AgentAuth getAgentAuth(Map<String, AttributeValue> attributes, String agentNameOverride, String applicationName, boolean allowApplicationNameFallback) {
        final String agentId = AttributeUtils.getAttributeStringValue(attributes, KEY_AGENT_ID, null);
        if (agentId != null) {
            if (!IdValidateUtils.validateId(agentId, PinpointConstants.AGENT_ID_MAX_LEN)) {
                throw new IllegalArgumentException("invalid pinpoint.agentId=" + agentId);
            }
            return new AgentAuth(agentId, resolveAgentName(agentNameOverride, agentId));
        }

        final String serviceInstanceId = AttributeUtils.getAttributeStringValue(attributes, KEY_SERVICE_INSTANCE_ID, null);
        if (serviceInstanceId != null) {
            return toAgentAuth(serviceInstanceId, KEY_SERVICE_INSTANCE_ID, agentNameOverride);
        }

        final String podUid = AttributeUtils.getAttributeStringValue(attributes, KEY_K8S_POD_UID, null);
        if (podUid != null) {
            return toAgentAuth(podUid, KEY_K8S_POD_UID, agentNameOverride);
        }

        final String containerId = AttributeUtils.getAttributeStringValue(attributes, KEY_CONTAINER_ID, null);
        if (containerId != null) {
            return toContainerAgentAuth(containerId, agentNameOverride);
        }

View on GitHub (pinned to 744c3d3075)