{"record":{"id":"146fc0c2600d9cca","repo":"pinpoint-apm/pinpoint","slug":"invalid-pinpoint-agentname-agentname","errorCode":null,"errorMessage":"invalid pinpoint.agentName=${agentName}","messagePattern":"invalid pinpoint\\.agentName=(.+?)","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":102,"sourceCode":"    public static IdAndName getId(Map<String, AttributeValue> attributes, boolean allowApplicationNameFallback) {\n        final String applicationName = getApplicationName(attributes);\n        final String agentNameOverride = getAgentNameOverride(attributes);\n        final AgentAuth agentAuth = getAgentAuth(attributes, agentNameOverride, applicationName, allowApplicationNameFallback);\n        final String serviceName = getServiceName(attributes);\n        return new IdAndName(agentAuth.agentId(), agentAuth.agentName(), applicationName, serviceName);\n    }\n\n    private static String resolveAgentName(String agentNameOverride, String defaultName) {\n        return agentNameOverride != null ? agentNameOverride : defaultName;\n    }\n\n    private static String getAgentNameOverride(Map<String, AttributeValue> attributes) {\n        final String agentName = AttributeUtils.getAttributeStringValue(attributes, KEY_AGENT_NAME, null);\n        if (agentName == null) {\n            return null;\n        }\n        if (!IdValidateUtils.validateId(agentName, PinpointConstants.AGENT_NAME_MAX_LEN_V4)) {\n            throw new IllegalArgumentException(\"invalid pinpoint.agentName=\" + agentName);\n        }\n        return agentName;\n    }\n\n    public static String getApplicationName(Map<String, AttributeValue> attributes) {\n        String applicationName = AttributeUtils.getAttributeStringValue(attributes, KEY_APPLICATION_NAME, null);\n        if (applicationName == null) {\n            applicationName = AttributeUtils.getAttributeStringValue(attributes, KEY_SERVICE_NAME, null);\n            if (applicationName == null) {\n                throw new IllegalArgumentException(\"not found applicationName\");\n            }\n        }\n        if (!IdValidateUtils.validateId(applicationName, PinpointConstants.APPLICATION_NAME_MAX_LEN_V3)) {\n            throw new IllegalArgumentException(\"invalid applicationName=\" + applicationName);\n        }\n\n        return applicationName;\n    }","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/otlptrace/otlptrace-collector/src/main/java/com/navercorp/pinpoint/otlp/trace/collector/mapper/OtlpTraceMapperUtils.java#L84-L120","documentation":"OtlpTraceMapperUtils.getAgentNameOverride reads the 'pinpoint.agentName' span/resource attribute as an agent-name override and validates it with IdValidateUtils.validateId against PinpointConstants.AGENT_NAME_MAX_LEN_V4. If the value is present but fails Pinpoint's ID rules (length or character set), IllegalArgumentException is thrown, rejecting the span batch.","triggerScenarios":"Sending OTLP spans carrying the pinpoint.agentName attribute whose value is empty, longer than AGENT_NAME_MAX_LEN_V4, or contains characters disallowed by Pinpoint's agent ID naming rules.","commonSituations":"Users configuring agentName overrides with spaces, slashes, or other special characters; long k8s pod-derived names exceeding the max length; configuration templating mistakes that leave the attribute empty; upgrading to V4 naming rules that are stricter than what old exporters emit.","solutions":["Change the pinpoint.agentName attribute value to conform to Pinpoint agent-name rules: within AGENT_NAME_MAX_LEN_V4 and using allowed characters (alphanumerics, '-', '_', '.').","Truncate or sanitize the value where the attribute is injected (e.g. k8s metadata enrichment) before export.","Remove the pinpoint.agentName attribute entirely if the default agent identification is sufficient (null is accepted and skips the override).","Pre-validate client-side with the same rule (length + allowed charset) before attaching the attribute."],"exampleFix":"// before\nattributes.put(\"pinpoint.agentName\", \"my agent / prod#1\"); // illegal chars\n// after\nattributes.put(\"pinpoint.agentName\", \"my-agent-prod-1\");","handlingStrategy":"validation","validationCode":"String agentName = attributes.get(\"pinpoint.agentName\");\nif (agentName != null && !agentName.matches(\"[a-zA-Z0-9._-]{1,\" + AGENT_NAME_MAX_LEN_V4 + \"}\")) {\n    throw new IllegalArgumentException(\"agentName violates Pinpoint naming rules: \" + agentName);\n}","typeGuard":"boolean isSafeAgentNameOverride(Map<String, AttributeValue> attrs) {\n    String v = AttributeUtils.getAttributeStringValue(attrs, \"pinpoint.agentName\", null);\n    return v == null || IdValidateUtils.validateId(v, PinpointConstants.AGENT_NAME_MAX_LEN_V4);\n}","tryCatchPattern":"try {\n    mapper.mapSpan(span);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().startsWith(\"invalid pinpoint.agentName\")) {\n        log.warn(\"dropping invalid agentName override: {}\", e.getMessage());\n    } else { throw e; }\n}","preventionTips":["Sanitize k8s/pod-derived names before injecting pinpoint.agentName","Keep the value within AGENT_NAME_MAX_LEN_V4 and the allowed character set","Omit the attribute rather than sending an empty or placeholder value","Share one validation utility between attribute producers and the collector"],"tags":["java","otlp","validation","naming"],"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-14T05:17:10.506Z"}