{"record":{"id":"f49ce9f1dad91d2b","repo":"pinpoint-apm/pinpoint","slug":"invalid-agentid-derived-from-applicationname-ap","errorCode":null,"errorMessage":"invalid agentId(derived from applicationName)=${applicationName}","messagePattern":"invalid agentId\\(derived from applicationName\\)=(.+?)","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":184,"sourceCode":"        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 {\n                final UUID uuid = UUID.fromString(id);\n                return new AgentAuth(Base64Utils.encode(uuid), resolveAgentName(agentNameOverride, id));\n            } catch (IllegalArgumentException ignore) {\n                // not a valid UUID string, fall through to treat as plain agentId\n            }\n        }\n        if (!IdValidateUtils.validateId(id, PinpointConstants.AGENT_ID_MAX_LEN)) {\n            throw new IllegalArgumentException(\"invalid \" + sourceKey + \"=\" + id);\n        }\n        return new AgentAuth(id, resolveAgentName(agentNameOverride, id));\n    }","sourceCodeStart":166,"sourceCodeEnd":202,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/otlptrace/otlptrace-collector/src/main/java/com/navercorp/pinpoint/otlp/trace/collector/mapper/OtlpTraceMapperUtils.java#L166-L202","documentation":"When the test/dev applicationName fallback is enabled and no real per-instance identifier exists, getAgentAuth derives the agentId from applicationName itself, but only if that value is a valid agentId (IdValidateUtils with AGENT_ID_MAX_LEN). Otherwise it throws this IllegalArgumentException.","triggerScenarios":"allowApplicationNameFallback=true, no other identifier attributes, and the resolved applicationName fails validateId — e.g. it is longer than AGENT_ID_MAX_LEN or contains invalid characters.","commonSituations":"Dev environments where the fallback flag was enabled but the applicationName (from service.name) is a long or punctuation-laden name that cannot double as an agentId.","solutions":["Shorten/normalize the applicationName (valid agentId charset, within AGENT_ID_MAX_LEN)","Provide a real per-instance identifier (service.instance.id) so the fallback path is not used","Pre-validate with IdValidateUtils.validateId(applicationName, PinpointConstants.AGENT_ID_MAX_LEN) before enabling the fallback"],"exampleFix":"// before\nexport OTEL_SERVICE_NAME=my-very-long-descriptive-service-name // exceeds agentId max\n// after\nexport OTEL_SERVICE_NAME=shortsvc","handlingStrategy":"validation","validationCode":"if (!IdValidateUtils.validateId(applicationName, PinpointConstants.AGENT_ID_MAX_LEN)) {\n    throw new IllegalArgumentException(\"invalid agentId(derived from applicationName)=\" + applicationName);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep applicationName valid as an agentId if you rely on the fallback","Provide a real per-instance id so the fallback is never exercised","Test fallback-enabled configs with the real service names"],"tags":["otlp","validation","agent-id"],"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"}