pinpoint-apm/pinpoint · error · IllegalArgumentException

invalid host.name=

Error message

invalid host.name=${hostName}

What it means

When no agentId, service.instance.id, k8s pod uid, or container id attribute exists, getAgentAuth falls back to the 'host.name' attribute as the per-instance identifier. If host.name is present but fails IdValidateUtils.validateId with AGENT_ID_MAX_LEN, this IllegalArgumentException is thrown because the hostname cannot serve as a valid Pinpoint agentId.

Solutions

1. Set a valid per-instance identifier instead: add 'service.instance.id' (e.g. uuidgen) or k8s.pod.uid attribute
2. Shorten/normalize the hostname to a valid agentId charset and length before export
3. Attach an explicit valid 'pinpoint.agentId' attribute that takes precedence over host.name

Example fix

// before
export OTEL_RESOURCE_ATTRIBUTES=host.name=app.prod.example.com // invalid as agentId
// after
export OTEL_RESOURCE_ATTRIBUTES=service.instance.id=$(uuidgen)

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

When it happens

Trigger: No agentId/serviceInstanceId/containerId attributes; 'pinpoint.host.name' (or KEY_HOST_NAME) attribute is non-null but its value violates validateId (too long, invalid characters like dots/underscores/colons typical of FQDNs).

Common situations: Hostnames that are fully-qualified domain names (app.prod.example.com), hostnames with underscores, or VM hostnames exceeding the agentId max length.

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 =
• invalid pinpoint.agentId=
• invalid pinpoint.agentName=

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

Appendix: source

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

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

        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 {

View on GitHub (pinned to 744c3d3075)