pinpoint-apm/pinpoint · error · IllegalArgumentException

no per-instance identifier — set service.instance.id (e.g…

Error message

no per-instance identifier — set service.instance.id (e.g. via uuidgen), k8s.pod.uid, container.id, or host.name. applicationName='${applicationName}'

What it means

getAgentAuth requires SOME per-instance identifier (service.instance.id, k8s pod uid, container id, host.name, or agentId) to build an AgentAuth. When none is present, it cannot distinguish instances and throws — unless the (disabled-by-default) applicationName fallback is explicitly enabled via pinpoint.collector.otlptrace.application-name-fallback.enabled.

Solutions

1. Set service.instance.id, e.g. OTEL_RESOURCE_ATTRIBUTES=service.instance.id=$(uuidgen)
2. On Kubernetes, ensure k8s.pod.uid is attached via the resource detector
3. Enable the collector's application-name fallback only for test/dev: set pinpoint.collector.otlptrace.application-name-fallback.enabled=true
4. Add host.name or container.id resource attributes so a per-instance id exists

Example fix

// before
// (no instance-level resource attributes)
// after
export OTEL_RESOURCE_ATTRIBUTES=service.instance.id=$(uuidgen),service.name=my-app

boolean hasId = Stream.of(KEY_AGENT_ID, KEY_SERVICE_INSTANCE_ID, KEY_HOST_NAME, "container.id", "k8s.pod.uid")
    .anyMatch(k -> AttributeUtils.getAttributeStringValue(attributes, k, null) != null);
if (!hasId) throw new IllegalStateException("no per-instance identifier in OTLP attributes");

try { AgentAuth a = getAgentAuth(attrs, override, app, false); } catch (IllegalArgumentException e) { log.error("OTLP span missing instance identifier: {}", e.getMessage()); }

When it happens

Trigger: OTLP span attributes contain none of KEY_AGENT_ID, KEY_SERVICE_INSTANCE_ID, pod-uid, container-id, KEY_HOST_NAME, and allowApplicationNameFallback is false (the default) at mapping time.

Common situations: Bare OTLP exporters (e.g. local dev scripts, libraries with default resource) that only set service.name; K8s pods without the downgraded pod-uid resource attribute; collector config where the fallback flag was left disabled.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• not found applicationName
• Failed to export. Worker executor rejected.
• invalid agentId(derived from applicationName)=
• invalid applicationName=
• invalid host.name=

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

Appendix: source

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

        }

        final String containerId = AttributeUtils.getAttributeStringValue(attributes, KEY_CONTAINER_ID, null);
        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);

View on GitHub (pinned to 744c3d3075)