pinpoint-apm/pinpoint · error · IllegalArgumentException

invalid agentId(derived from applicationName)=

Error message

invalid agentId(derived from applicationName)=${applicationName}

What it means

When the test/dev applicationName fallback is enabled and no real per-instance identifier exists, getAgentAuth derives the agentId from applicationName itself, but only if that value is a valid agentId (IdValidateUtils with AGENT_ID_MAX_LEN). Otherwise it throws this IllegalArgumentException.

Solutions

1. Shorten/normalize the applicationName (valid agentId charset, within AGENT_ID_MAX_LEN)
2. Provide a real per-instance identifier (service.instance.id) so the fallback path is not used
3. Pre-validate with IdValidateUtils.validateId(applicationName, PinpointConstants.AGENT_ID_MAX_LEN) before enabling the fallback

Example fix

// before
export OTEL_SERVICE_NAME=my-very-long-descriptive-service-name // exceeds agentId max
// after
export OTEL_SERVICE_NAME=shortsvc

if (!IdValidateUtils.validateId(applicationName, PinpointConstants.AGENT_ID_MAX_LEN)) {
    throw new IllegalArgumentException("invalid agentId(derived from applicationName)=" + applicationName);
}

When it happens

Trigger: allowApplicationNameFallback=true, no other identifier attributes, and the resolved applicationName fails validateId — e.g. it is longer than AGENT_ID_MAX_LEN or contains invalid characters.

Common situations: Dev environments where the fallback flag was enabled but the applicationName (from service.name) is a long or punctuation-laden name that cannot double as an agentId.

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 pinpoint.agentId=
• 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/f49ce9f1dad91d2b. Report an issue: GitHub.

Appendix: source

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

        if (containerId != null) {
            return toContainerAgentAuth(containerId, agentNameOverride);
        }

        final String hostName = AttributeUtils.getAttributeStringValue(attributes, KEY_HOST_NAME, null);
        if (hostName != null) {
            if (!IdValidateUtils.validateId(hostName, PinpointConstants.AGENT_ID_MAX_LEN)) {
                throw new IllegalArgumentException("invalid host.name=" + hostName);
            }
            return new AgentAuth(hostName, resolveAgentName(agentNameOverride, hostName));
        }

        // applicationName fallback — test/dev environment only.
        // Gated by pinpoint.collector.otlptrace.application-name-fallback.enabled (default: false).
        if (!allowApplicationNameFallback) {
            throw new IllegalArgumentException("no per-instance identifier — set service.instance.id (e.g. via uuidgen), k8s.pod.uid, container.id, or host.name. applicationName='" + applicationName + "'");
        }
        if (!IdValidateUtils.validateId(applicationName, PinpointConstants.AGENT_ID_MAX_LEN)) {
            throw new IllegalArgumentException("invalid agentId(derived from applicationName)=" + applicationName);
        }
        return new AgentAuth(applicationName, resolveAgentName(agentNameOverride, applicationName));
    }

    private static AgentAuth toAgentAuth(String id, String sourceKey, String agentNameOverride) {
        if (id.length() == 36) {
            try {
                final UUID uuid = UUID.fromString(id);
                return new AgentAuth(Base64Utils.encode(uuid), resolveAgentName(agentNameOverride, id));
            } catch (IllegalArgumentException ignore) {
                // not a valid UUID string, fall through to treat as plain agentId
            }
        }
        if (!IdValidateUtils.validateId(id, PinpointConstants.AGENT_ID_MAX_LEN)) {
            throw new IllegalArgumentException("invalid " + sourceKey + "=" + id);
        }
        return new AgentAuth(id, resolveAgentName(agentNameOverride, id));
    }

View on GitHub (pinned to 744c3d3075)