pinpoint-apm/pinpoint · error · IllegalArgumentException

invalid ${sourceKey}=${id}

Error message

invalid ${sourceKey}=${id}

What it means

toAgentAuth converts a resolved identifier (e.g. a service.instance.id value) into an AgentAuth. It first tries to interpret 36-char values as UUIDs; failing that, it validates the raw id with IdValidateUtils (AGENT_ID_MAX_LEN). An id with disallowed characters or excessive length throws this IllegalArgumentException with the source attribute key named in the message.

Source

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

            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));
    }

    private static AgentAuth toContainerAgentAuth(String containerId, String agentNameOverride) {
        // Docker/containerd full ID: 64 lowercase hex chars (SHA256).
        // Truncate to first 16 bytes → 22-char URL-safe Base64 (same format as UUID case).
        if (containerId.length() == CONTAINER_ID_FULL_HEX_LEN) {
            try {
                final byte[] bytes = Base16Utils.decodeToBytes(containerId);
                final byte[] prefix = Arrays.copyOf(bytes, AGENT_ID_HASH_PREFIX_BYTES);
                return new AgentAuth(Base64Utils.encode(prefix), resolveAgentName(agentNameOverride, containerId));
            } catch (IllegalArgumentException ignore) {
                // not valid hex, fall through to treat as plain agentId
            }
        }
        if (!IdValidateUtils.validateId(containerId, PinpointConstants.AGENT_ID_MAX_LEN)) {
            throw new IllegalArgumentException("invalid " + KEY_CONTAINER_ID + "=" + containerId);

View on GitHub (pinned to 744c3d3075)

Solutions

1. Set service.instance.id to either a valid agentId string or a bare 36-char UUID (uuidgen output, no urn: prefix)
2. Strip hyphens or disallowed characters from the id before export
3. Use k8s.pod.uid or container.id, which are hex and validate cleanly

Example fix

// before
OTEL_RESOURCE_ATTRIBUTES=service.instance.id=urn:uuid:550e8400-e29b...
// after
OTEL_RESOURCE_ATTRIBUTES=service.instance.id=550e8400e29b41d4a716446655440000

if (!isUuid(id) && !IdValidateUtils.validateId(id, PinpointConstants.AGENT_ID_MAX_LEN)) {
    throw new IllegalArgumentException("invalid identifier=" + id);
}

boolean isValidInstanceId(String id) {
    return (id.length() == 36 && UUID.fromString(id) != null) || IdValidateUtils.validateId(id, PinpointConstants.AGENT_ID_MAX_LEN);
}

When it happens

Trigger: getAgentAuth passes a service.instance.id (or similar) value to toAgentAuth that is not a UUID and fails validateId — e.g. contains '-', '@', spaces, or is longer than AGENT_ID_MAX_LEN.

Common situations: service.instance.id set to values with hyphens (non-UUID style like 'pod-abc-123'), emails, or URNs (urn:uuid:... instead of the bare UUID).

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 applicationName=${applicationName}
• sqlUid length must be 16: ${sqlUid.length}
• Resource attribute `service.name` is required to save OTLP m
• Resource attribute `pinpoint.agentId` is required to save OT
• invalid traceId: ${error}

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