{"record":{"id":"cadfa587e183257a","repo":"pinpoint-apm/pinpoint","slug":"invalid-host-name-hostname","errorCode":null,"errorMessage":"invalid host.name=${hostName}","messagePattern":"invalid host\\.name=(.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"otlptrace/otlptrace-collector/src/main/java/com/navercorp/pinpoint/otlp/trace/collector/mapper/OtlpTraceMapperUtils.java","lineNumber":173,"sourceCode":"        final String serviceInstanceId = AttributeUtils.getAttributeStringValue(attributes, KEY_SERVICE_INSTANCE_ID, null);\n        if (serviceInstanceId != null) {\n            return toAgentAuth(serviceInstanceId, KEY_SERVICE_INSTANCE_ID, agentNameOverride);\n        }\n\n        final String podUid = AttributeUtils.getAttributeStringValue(attributes, KEY_K8S_POD_UID, null);\n        if (podUid != null) {\n            return toAgentAuth(podUid, KEY_K8S_POD_UID, agentNameOverride);\n        }\n\n        final String containerId = AttributeUtils.getAttributeStringValue(attributes, KEY_CONTAINER_ID, null);\n        if (containerId != null) {\n            return toContainerAgentAuth(containerId, agentNameOverride);\n        }\n\n        final String hostName = AttributeUtils.getAttributeStringValue(attributes, KEY_HOST_NAME, null);\n        if (hostName != null) {\n            if (!IdValidateUtils.validateId(hostName, PinpointConstants.AGENT_ID_MAX_LEN)) {\n                throw new IllegalArgumentException(\"invalid host.name=\" + hostName);\n            }\n            return new AgentAuth(hostName, resolveAgentName(agentNameOverride, hostName));\n        }\n\n        // applicationName fallback — test/dev environment only.\n        // Gated by pinpoint.collector.otlptrace.application-name-fallback.enabled (default: false).\n        if (!allowApplicationNameFallback) {\n            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 + \"'\");\n        }\n        if (!IdValidateUtils.validateId(applicationName, PinpointConstants.AGENT_ID_MAX_LEN)) {\n            throw new IllegalArgumentException(\"invalid agentId(derived from applicationName)=\" + applicationName);\n        }\n        return new AgentAuth(applicationName, resolveAgentName(agentNameOverride, applicationName));\n    }\n\n    private static AgentAuth toAgentAuth(String id, String sourceKey, String agentNameOverride) {\n        if (id.length() == 36) {\n            try {","sourceCodeStart":155,"sourceCodeEnd":191,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/otlptrace/otlptrace-collector/src/main/java/com/navercorp/pinpoint/otlp/trace/collector/mapper/OtlpTraceMapperUtils.java#L155-L191","documentation":"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.","triggerScenarios":"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).","commonSituations":"Hostnames that are fully-qualified domain names (app.prod.example.com), hostnames with underscores, or VM hostnames exceeding the agentId max length.","solutions":["Set a valid per-instance identifier instead: add 'service.instance.id' (e.g. uuidgen) or k8s.pod.uid attribute","Shorten/normalize the hostname to a valid agentId charset and length before export","Attach an explicit valid 'pinpoint.agentId' attribute that takes precedence over host.name"],"exampleFix":"// before\nexport OTEL_RESOURCE_ATTRIBUTES=host.name=app.prod.example.com // invalid as agentId\n// after\nexport OTEL_RESOURCE_ATTRIBUTES=service.instance.id=$(uuidgen)","handlingStrategy":"validation","validationCode":"String hostName = AttributeUtils.getAttributeStringValue(attributes, KEY_HOST_NAME, null);\nif (hostName != null && !IdValidateUtils.validateId(hostName, PinpointConstants.AGENT_ID_MAX_LEN)) {\n    throw new IllegalArgumentException(\"invalid host.name=\" + hostName);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use short hostnames (not FQDNs) when host.name is used as identity","Prefer service.instance.id over host.name for per-instance identity","Sanitize hostname characters before export"],"tags":["otlp","validation","hostname"],"backgroundTag":"invalid-identifier-format","analyzedSha":"744c3d3075e595656abb1ae331ad2c0e4c9eb996","analyzedAt":"2026-09-07T18:48:45.289Z","contentChangedAt":"2026-09-07T18:48:45.289Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}